Mastering .NET Assembly Versions: Differentiate Between AssemblyVersion and AssemblyFileVersion

Table of Contents

Understanding how .NET manages assembly versions is crucial for developing and deploying robust applications. Two primary attributes, AssemblyVersion and AssemblyFileVersion, play distinct roles in this process. While both relate to versioning, they serve different purposes within the .NET ecosystem and the operating system’s file system. This article delves into the functionalities of these two attributes, explaining their significance and how they are utilized.

Developing software involves managing dependencies and ensuring compatibility between different components. In the .NET world, assemblies are the fundamental units of deployment, versioning, and security. Proper versioning allows the Common Language Runtime (CLR) to locate and load the correct assembly versions required by an application. It also helps developers track changes and manage releases effectively.

The Dual Nature of .NET Assembly Versioning¶

Microsoft’s .NET Framework and subsequent versions provide mechanisms to assign multiple version numbers to a single assembly. This approach caters to different needs: identification by the runtime for loading and linking, and identification within the file system for administrative purposes. These two distinct requirements are met by the AssemblyVersion and AssemblyFileVersion attributes, respectively. Distinguishing between them is key to avoiding common deployment and referencing issues.

While it might seem redundant to have two version numbers, their separation provides flexibility. AssemblyVersion is critical for the CLR’s internal operations, influencing how assemblies are found and bound at runtime. AssemblyFileVersion, on the other hand, acts more like a traditional file property, visible through standard operating system tools and useful for tracking specific build outputs.

Understanding AssemblyVersion¶

The AssemblyVersion attribute defines the version number that the .NET framework uses internally. This version is paramount during the build process when compiling code that references other assemblies. When you add a reference to an assembly in your project, the AssemblyVersion of the referenced assembly is embedded into your project’s metadata. This creates a binding dependency specifying which version of the dependency your assembly expects.

Purpose and Role in Binding¶

At runtime, the Common Language Runtime (CLR) uses the AssemblyVersion to locate and load the required assembly. This process is part of assembly binding. For strong-named assemblies, the CLR considers the AssemblyVersion along with the assembly’s name, public key token, and culture information to uniquely identify the assembly. If the assembly is not strong-named, the CLR primarily relies on the file name, potentially leading to conflicts if multiple versions of a weak-named assembly exist in locations the CLR probes.

The structure of the AssemblyVersion typically follows the format Major.Minor.Build.Revision. Each part of the version number provides information about the changes introduced in that specific version. Incrementing the major or minor version usually indicates significant changes or potential breaking changes, while build and revision numbers often track smaller updates or bug fixes.

Strong Naming and Version Policy¶

Strong naming an assembly adds a cryptographic signature, a public key, and the assembly’s identity (including AssemblyVersion) to the assembly manifest. This ensures that the assembly is unique and tamper-proof. For strong-named assemblies, the CLR enforces strict version binding by default. This means an application compiled against version 1.0.0.0 of a strong-named assembly will, by default, only load exactly version 1.0.0.0 of that assembly at runtime.

This strict enforcement guarantees that an application uses the specific version it was tested against, reducing the risk of unexpected behavior due to incompatible assembly updates. However, it can also lead to the “DLL Hell” scenario if multiple applications on the same system require different specific versions of the same assembly. .NET’s version policy, especially through configuration files, allows overriding this strict binding behavior.

Versioning Automatic Increments¶

The AssemblyVersion attribute in AssemblyInfo.cs is typically set manually, but it can also be configured for automatic increments. Using an asterisk (*) in place of the Build or Revision number (e.g., [assembly: AssemblyVersion("1.0.*")]) instructs the compiler to automatically generate the corresponding part of the version number.

When AssemblyVersion("1.0.*") is used, the Build number is typically calculated as the number of days since January 1, 2000 (local time), and the Revision number is the number of seconds since midnight (local time), divided by 2. This automatic generation ensures a unique AssemblyVersion for every build, which can be useful for tracking specific build outputs but can also pose challenges for strict version binding if not managed carefully, potentially requiring frequent use of binding redirects.

Managing Version Conflicts with Binding Redirects¶

Strict AssemblyVersion binding for strong-named assemblies can cause issues when a newer, compatible version of a dependency is available, but an application is compiled against an older one. To address this, .NET allows the use of binding redirects. These are configuration settings, typically placed in the application’s app.config or web.config file, that instruct the CLR to load a different version of an assembly than the one specified in the application’s references.

A binding redirect maps a requested version range to a specific new version. For example, it can tell the CLR that any request for MyAssembly version 1.0.0.0 through 1.9.9.9 should instead load version 2.0.0.0. This allows multiple applications that were built against different older versions of a strong-named assembly to share a single, newer, compatible version installed on the system, promoting side-by-side execution capabilities or simply allowing updates without recompiling dependent applications.

<configuration>
   <runtime>
      <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
         <dependentAssembly>
            <assemblyIdentity name="MyAssembly"
                              publicKeyToken="a1b2c3d4e5f6g7h8"
                              culture="neutral" />
            <bindingRedirect oldVersion="1.0.0.0-1.9.9.9"
                             newVersion="2.0.0.0"/>
         </dependentAssembly>
      </assemblyBinding>
   </runtime>
</configuration>

This XML snippet demonstrates how to redirect requests for MyAssembly versions from 1.0.0.0 up to (but not including) 2.0.0.0 to load version 2.0.0.0 instead. This mechanism is powerful but requires careful consideration of backward compatibility between the old and new assembly versions.

Understanding AssemblyFileVersion¶

In contrast to AssemblyVersion, the AssemblyFileVersion attribute defines the version number assigned to the assembly file itself within the file system. This version is stored in the Win32 version information resource of the compiled assembly file (typically a .dll or .exe).

Purpose and Role in the File System¶

The AssemblyFileVersion is primarily for informational purposes and is displayed by operating system tools. For example, when you view the properties of a .NET assembly file in Windows Explorer, the ‘Details’ tab shows the “File version,” which corresponds to the value set by the AssemblyFileVersion attribute. This version is useful for tracking the exact build or release of a specific file on disk.

Unlike AssemblyVersion, AssemblyFileVersion has no bearing on the .NET runtime’s assembly binding process. The CLR completely ignores this version number when resolving assembly references. It is purely metadata associated with the file itself, used outside of the .NET runtime’s core loading mechanisms.

Relation to Win32 File Version Resource¶

The value specified in the AssemblyFileVersion attribute is written into the standard Win32 version resource block of the generated executable or library file. This is the same mechanism used by native Windows applications to store version information. This ensures that the file integrates seamlessly with Windows shell features and versioning tools.

This attribute allows developers to decouple the file’s visible version from the runtime’s binding version. For instance, you could have an AssemblyVersion of “1.0.0.0” to maintain compatibility for runtime binding while having an AssemblyFileVersion of “1.0.123.4567” to indicate a specific build number from your continuous integration system.

Versioning Automatic Increments¶

Similar to AssemblyVersion, the AssemblyFileVersion can also use an asterisk (*) for automatic incrementation. When [assembly: AssemblyFileVersion("1.0.*")] is used, the compiler generates the Build and Revision numbers automatically based on the date and time of the build, using the same algorithm as AssemblyVersion.

Automatic AssemblyFileVersion generation is very common, especially in automated build pipelines. It provides a unique identifier for each specific build output, making it easy to trace which code commit or build run produced a particular assembly file. Since this version is not used by the CLR for binding, automatically incrementing it rarely causes runtime issues related to version mismatches.

Beyond AssemblyVersion and AssemblyFileVersion: AssemblyInformationalVersion¶

While AssemblyVersion and AssemblyFileVersion are the primary versioning attributes discussed, the AssemblyInformationalVersion attribute is also frequently used and worth mentioning. This attribute allows specifying a product version string, which can contain more detailed information than the strict four-part number format required by AssemblyVersion and AssemblyFileVersion.

The AssemblyInformationalVersion is stored in the AssemblyInformationalVersionAttribute. It is also included in the Win32 version resource block, often appearing as the “Product version” in file properties. It is not used by the CLR for binding and serves purely as an informational string. This string can include build metadata, source control information (like commit hashes), or marketing version numbers (e.g., “1.0 Release Candidate 1”).

Using AssemblyInformationalVersion allows teams to provide richer version details visible to users or administrators without impacting the runtime behavior governed by AssemblyVersion. Build servers commonly set this attribute based on the specifics of the build process.

Practical Application and Best Practices¶

Choosing how to use AssemblyVersion and AssemblyFileVersion depends on your project’s needs and deployment strategy. A common practice is to manually control AssemblyVersion and only increment the major or minor number when breaking changes are introduced. This minimizes the need for binding redirects.

Choosing a Versioning Strategy¶

For AssemblyFileVersion, using automatic incrementation via the asterisk is a popular strategy, especially in automated build environments. This ensures that every build produces a file with a unique version visible in the file system, aiding traceability. Some teams also choose to keep AssemblyVersion and AssemblyFileVersion the same, particularly for simpler applications or when not using strong naming extensively. However, separating them provides greater flexibility.

A recommended strategy is to set AssemblyVersion to a fixed major.minor.build.revision that changes only when compatibility breaks or major features are added. Set AssemblyFileVersion to automatically generate using * or set it to a version derived from your build system’s build number or source control commit hash. Set AssemblyInformationalVersion to a human-readable string that might include the marketing version, build number, and potentially a commit hash.

Integrating with Build Systems¶

Continuous Integration (CI) and Continuous Deployment (CD) pipelines are ideal places to manage assembly versioning. Build scripts can dynamically update the AssemblyVersion, AssemblyFileVersion, and AssemblyInformationalVersion attributes in the AssemblyInfo.cs file (or project file for newer SDK-style projects) before compilation. This ensures consistent and automated versioning based on the build process or source control state.

For example, a CI pipeline could use the build number as the Build and Revision parts of AssemblyFileVersion and AssemblyInformationalVersion, while keeping AssemblyVersion static until a planned release that might break compatibility. Tools like GitVersion can even derive semantic version numbers based on Git history and apply them to assembly attributes.

Inspecting Assembly Versions¶

Several tools can be used to inspect the version information of a compiled .NET assembly:

1. Windows Explorer File Properties: Right-click the assembly file (.dll or .exe), select “Properties,” and go to the “Details” tab. This shows “File version” (AssemblyFileVersion) and “Product version” (AssemblyInformationalVersion).
2. ILDASM (IL Disassembler): This tool, included with the .NET SDK, can disassemble an assembly and show its manifest, which includes the AssemblyVersion.
3. Assembly.Load or Assembly.GetExecutingAssembly() in code: Programmatically, you can load an assembly and access its GetName() method to get the AssemblyVersion. You can also access custom attributes like AssemblyFileVersionAttribute and AssemblyInformationalVersionAttribute.
4. fuslogvw (Assembly Binding Log Viewer): This tool helps diagnose assembly binding issues by logging the CLR’s attempts to locate and load assemblies. It shows which AssemblyVersion the CLR was looking for and where it probed.

Inspecting these versions is crucial for debugging deployment issues, verifying build outputs, and ensuring dependencies are resolved correctly.

Visualizing the Concepts¶

Let’s summarize the roles of the versions in a simplified table:

Attribute	Role	Used by CLR for Binding?	Where Visible?	Recommended Strategy
AssemblyVersion	Runtime Binding, Referencing	Yes (especially strong-named)	Assembly Manifest, References	Manual (change only for compatibility breaks/features)
AssemblyFileVersion	File System Version	No	Windows Explorer (File version)	Automatic (*) or Build Number
AssemblyInformationalVersion	Product/Informational String	No	Windows Explorer (Product version)	Marketing Version + Build Info (e.g., “1.0-beta.5+commit”)

Understanding this distinction helps clarify why an assembly might display one version in Explorer but cause runtime errors if a different version is expected by the CLR.

mermaid graph LR A[Source Code] --> B(Compiler); B --> C{Assembly File (.dll/.exe)}; C --> D1[Assembly Manifest (AssemblyVersion)]; C --> D2[Win32 Version Resource (AssemblyFileVersion, AssemblyInformationalVersion)]; D1 --> E1[CLR Runtime (Binding, Loading)]; D2 --> E2[Operating System Tools (Explorer Properties)]; E1 --> F[Application Execution]; E2 --> G[User/Admin Information];
This diagram illustrates how the different version attributes end up in different parts of the compiled assembly and are consumed by different entities (CLR vs. OS tools).

Further Exploration¶

To deepen your understanding of .NET assembly versioning, particularly the intricacies of binding, probing, and binding redirects, exploring official Microsoft documentation and videos on the subject is highly recommended. Topics like “CLR Assembly Binding” and “How the Runtime Locates Assemblies” provide valuable insights.

Consider searching platforms like YouTube for demonstrations on setting up automated versioning using build servers like Azure DevOps, GitHub Actions, or Jenkins, or using tools like GitVersion. Visualizing these concepts in a practical build pipeline can solidify your understanding of how these attributes are managed in real-world scenarios.

Conclusion¶

While seemingly similar, AssemblyVersion and AssemblyFileVersion serve fundamentally different purposes in the .NET ecosystem. AssemblyVersion is the runtime identifier, crucial for dependency resolution and binding, especially with strong-named assemblies. AssemblyFileVersion is a file system metadata version, useful for tracking specific build outputs but ignored by the CLR for binding. AssemblyInformationalVersion provides additional descriptive version details. Mastering the use and distinction of these attributes is vital for building, deploying, and troubleshooting .NET applications effectively, ensuring compatibility and simplifying maintenance.

How do you manage versioning in your .NET projects? Do you use automatic versioning, or do you prefer manual control? Share your strategies and experiences in the comments below!