DLL and COM Interface Backward Compatibility — A Decision Table for Which Changes Break Callers

“Can we just swap in the new DLL for this fix, or do the callers need a rebuild too?” — if you maintain a shared DLL or COM component that multiple applications reference, you end up answering this question at every release. Get it wrong, and an old EXE still running at a client site can stop launching entirely, or worse, it keeps launching just fine while its calculation results quietly change underneath it.

What makes this tricky is that the call tends to get made on a vague “this feels risky” hunch. In reality, which changes break compatibility can be determined almost mechanically. Native DLLs have well-defined rules around exports and calling conventions; COM has the explicit, written-down iron rule that interfaces are immutable¹; and .NET has a published list of compatibility change rules that Microsoft itself uses when developing the .NET libraries².

On this blog, we’ve already covered the basics of COM in What Is COM / ActiveX / OCX? and its design philosophy in What Is COM — Why Windows COM’s Design Still Holds Up Today. This article organizes, as a decision table, which changes break callers for DLLs, COM, and .NET assemblies respectively, and covers the procedure to follow when breaking compatibility becomes unavoidable.

1. The Bottom Line First

• Compatibility has three layers: binary compatibility (works without a rebuild), source compatibility (works if you rebuild), and behavioral compatibility (behavior doesn’t change). “No rebuild required” does not equal “safe” — you need to judge behavioral compatibility too.³
• For native DLLs, the baseline rule is adding an export is safe; changing or removing an existing export is breaking. Function signatures, calling conventions, and struct layout are the binary contract itself.
• A COM interface is immutable once published. Adding, removing, or reordering methods after publication violates the specification; changes must be added as a new interface with a new IID (IFoo → IFoo2).⁴¹
• VB6/VBA clients use early binding, which bakes in vtable slot positions, making them the callers most likely to break from any change to an interface’s layout.
• For .NET, what counts as a breaking change to a public API is published as Microsoft’s compatibility change rules, and the list classifies not just method removal or signature changes but also adding virtual to a member and even renaming a parameter as breaking.²
• Semantic versioning is a convention of bumping the major version on a breaking change, but it only works once you declare a definition of what counts as breaking.⁵ You can use this article’s decision table as that definition.
• When breaking compatibility is unavoidable, proceed in this order: offer old and new side by side → a deprecation period → an inventory of callers → retirement. The principle is never to swap it out all at once.

2. The Three Layers of Compatibility — Who Breaks, and When

What gets casually lumped together as “backward compatibility” actually breaks down into three layers. Even .NET’s official documentation classifies breaking changes along the lines of source, binary, and behavioral compatibility.³

The important point about these three layers is that an outer layer can break even when an inner layer stays intact. For example, a fix that changes the meaning of an existing function’s return value keeps both binary and source compatibility intact while breaking only behavioral compatibility. Because this kind of change produces neither a link error nor a compile error, it’s the row in the decision table that’s easiest to overlook.

Conversely, in an environment where every caller holds the source and can be rebuilt at the same time (a single-repo in-house system, say), you only need to preserve source and behavioral compatibility — binary compatibility can be dropped from the requirements. Whether any caller of your DLL is a binary you can’t rebuild is the first fork in the road when reading the decision table.

3. The Compatibility Decision Table for Native DLLs (C/C++)

A native DLL’s compatibility is determined by its export table, calling conventions, and memory layout. How a DLL gets found and loaded in the first place is covered in How Windows DLL Name Resolution Works; once loading succeeds, the table below is how you judge compatibility.

The design guidance this table leads to hasn’t changed in decades: keep the boundary to a C ABI (extern "C" functions and plain structs), and extend by adding functions. The same applies even when you’re building a native DLL from C#: the export surface covered in How to Call a C# Native AOT DLL From C/C++ is managed exactly according to this table.

3.1 The cbSize Convention — Win32’s Trick for Making Structs Extensible

The classic countermeasure to “adding a struct member breaks callers” is the Win32 convention of putting a size field at the head of the struct. The caller fills in cbSize with the struct size it knew about at compile time and passes that in; the DLL looks at that size to determine which generation of the struct this particular caller understands.

typedef struct KS_CONFIG {
    DWORD cbSize;      // The caller sets sizeof(KS_CONFIG)
    DWORD dwMode;
    DWORD dwTimeout;
    // Always add future members at the end
} KS_CONFIG;

// DLL side: use cbSize to tell generations apart, and fall back to a default for old callers
if (pConfig->cbSize >= FIELD_OFFSET(KS_CONFIG, dwTimeout) + sizeof(DWORD)) {
    timeout = pConfig->dwTimeout;   // New caller
} else {
    timeout = DEFAULT_TIMEOUT;      // Old caller
}

In fact, the Windows API’s NOTIFYICONDATA struct is versioned by generation using exactly this scheme, and it’s officially documented that setting the right value in cbSize lets you stay compatible with older versions of Shell32.dll.⁶ If you put cbSize into your own DLL’s public structs starting from the very first version, later extensions move from “breaking change” to the safe side of the decision table. That said, new members must always go at the end, and changing the type or order of an existing member is still forbidden. There’s one more thing: for a struct used for output, the DLL side takes on extra responsibility — writes and initialization must always stay within the cbSize the caller actually passed in. Unconditionally writing the full new sizeof overruns the smaller buffer an old caller allocated, and the DLL ends up causing exactly the kind of breakage this convention was supposed to prevent.

4. The Iron Rule of COM Interfaces — No Changes Once Published

COM is the technology that gave the clearest answer to this problem. Under the COM specification, an interface follows these rules:

• An interface has a unique IID (interface ID).¹
• An interface is immutable. Once created and published, no part of its definition may ever be changed.¹
• Adding or removing a method, or changing its semantics, doesn’t mean creating “a new version of the old interface” — it means creating a new interface with a different IID.⁴

The reason for such strictness is that a COM interface’s real substance is a binary layout — the vtable, a table of function pointers. A C++ or VB6 client bakes in, at compile time, the fact that “slot 3 is GetName” — a position. Insert a method after publication, and the old client will, with no error at all, call a different method. That’s exactly why COM erased the very operation of “changing” an interface from the spec, and provided the following extension procedure instead.

// v1: already published. Never change this again
[object, uuid(1111....)]
interface ICalc : IUnknown {
    HRESULT Add([in] long a, [in] long b, [out, retval] long* result);
};

// v2: a new interface with a new IID. Extends by inheriting from ICalc
[object, uuid(2222....)]
interface ICalc2 : ICalc {
    HRESULT AddChecked([in] long a, [in] long b, [out, retval] long* result);
};

The implementing class (the coclass) implements both ICalc and ICalc2; old clients keep using ICalc exactly as before, and new clients request ICalc2 via QueryInterface. The official versioning theory for RPC/COM lays it out the same way: a new interface that inherits from the old one is the equivalent of a minor version bump, while changing an existing method or type requires an entirely new, non-inheriting interface — the equivalent of a major version bump.⁷ What makes this scheme work is that QueryInterface lets a caller safely check, at run time, which interfaces are supported. The design elegance behind this mechanism is something we dug into in What Is COM.

4.1 Dividing Responsibility Among CLSID, ProgID, and IID

When thinking about COM versioning, it helps to separate the roles of three kinds of identifiers.⁸

• IID identifies an interface (a contract). Any change to the contract always means a new IID.
• CLSID identifies the implementing class. You’re free to swap the implementation while keeping the same CLSID, as long as you honor the contract of every published interface.
• ProgID is a human-readable alias (KomuraSoft.Calc.1) used to look up the corresponding CLSID in the registry. It’s conventional to keep both a version-numbered ProgID and a version-independent ProgID (KomuraSoft.Calc) that always points at the latest version, with the latter mapped to the current version via CurVer.⁸

In other words, “upgrading the implementation” belongs to the world of CLSID and ProgID, while “changing the contract” belongs to the world of IID — don’t conflate the two. If you’d rather avoid registry registration altogether, that option is covered in What Is Reg-Free COM?

4.2 Why VB6/VBA Clients Are Especially Fragile

When VB6 or VBA uses a COM component through a project reference (early binding), it reads the type library at compile time to resolve calls. Early binding is the recommended form — you get IntelliSense, type checking, and faster execution⁹ — but the price is that it binds tightly to the type library’s layout. Not only does an interface’s vtable changing cause trouble; even a change purely to the type library’s definitions can surface as “the reference was broken when I opened the project” or as runtime error 430/438.

That means components with VB6, VBA, or Excel macros as callers need to enforce the interface-immutability rule most strictly of all. Type libraries also carry a version (major.minor), and you bump it whenever you extend the contract. Generating a type library when you’re publishing typed .NET code to VBA is covered in Calling a Typed .NET 8 DLL From VBA — dscom and TLB. Late-bound clients that only use CreateObject, on the other hand, resolve by name and so are resilient to layout changes, but they’re just as exposed to a change in a method’s meaning (behavioral compatibility).

5. .NET Assembly Compatibility — Judging It Mechanically With the Official Rules

.NET has a published set of “change rules for compatibility” that Microsoft itself uses when developing the .NET libraries, classifying each kind of change as allowed (✔️), forbidden (❌), or needs-judgment (❓).² The documentation explicitly states you can adopt it as-is as the criteria for your own libraries, so here are the main rows.

It isn’t as simple as COM’s “interfaces are immutable,” but the underlying philosophy is the same: a public API is a contract; you can add to the contract, but you cannot change the existing contract. And the fact that changes like adding a virtual method or renaming a parameter — the kind of thing that looks safe at a glance — are classified as breaking is exactly why you should judge by the table rather than by feel.

5.1 Strong Names and Three Version Numbers

.NET assemblies carry several version numbers, each with a different role.¹⁰

• AssemblyVersion: the only version the runtime uses to identify and load an assembly. For strong-named assemblies, .NET Framework’s CLR requires an exact match, so every bump forces callers to add a binding redirect (.NET / .NET Core, by contrast, accepts a higher version automatically). To cut down on redirects, official guidance suggests reflecting only the major version in AssemblyVersion.
• FileVersion (AssemblyFileVersion): visible only in Explorer’s file properties, with no effect on runtime behavior. It’s the recommended place to stamp in a CI build number.
• InformationalVersion: a free-form, human-facing string. Used to record a semver-formatted package version or the source commit hash.

In practice, then, the workable three-tier setup is: declare compatibility through the package/product version (semver), reflect only the major version in AssemblyVersion, and track builds with FileVersion.

6. How to Assign Version Numbers — Semver Only Works Once You Have a “Definition”

Semantic versioning (semver) fits in three lines: bump MAJOR for an incompatible change, MINOR for a backward-compatible feature addition, and PATCH for a backward-compatible bug fix.⁵

What’s easy to overlook is that the semver spec’s very first requirement is that software using semver must declare a public API.⁵ Without declaring what counts as the public API, there’s no criterion for what an “incompatible change” even is, and whether to bump the major version comes down to whoever’s mood that day. In most places where semver isn’t actually working, the problem isn’t how the numbers are assigned — it’s that this declaration got skipped.

A realistic operating model for a DLL distributed internally looks like this.

1. Declare the scope of the public API — for a native DLL, that’s the exported functions and public headers; for COM, the IDL/type library; for .NET, public types and members. State explicitly that “anything outside this is an internal implementation detail that can change without notice.”
2. Adopt a definition of a breaking change — put this article’s decision tables from Chapters 3 and 5, along with .NET’s change rules², into your repository as “our own definition.”
3. Automate the check — for .NET, tools like Package Validation and ApiCompat can mechanically verify binary compatibility against the previous version.¹¹ This eliminates the “probably fine” judgment call during review.
4. Add a compatibility field to the release notes — spell out, every single time, one of three values: no rebuild needed / rebuild recommended / breaking change included. This is a mechanism for putting the answer to “can we just swap in the new DLL?” in writing before anyone even has to ask.

7. The Procedure for When Breaking Compatibility Is Unavoidable

When a change that the decision table flags as breaking turns out to be unavoidable, proceed by offering both versions side by side rather than swapping one out for the other.

1. Offer old and new side by side — for COM, that’s adding IFoo2 while leaving IFoo in place (Chapter 4). For a native DLL, add a new function (FooEx) or let a differently named new DLL coexist with the old one. For .NET, ship the change as a new package with a bumped major version, and keep the old major version alive for bug fixes only.
2. Set a deprecation period — in .NET, the [Obsolete] attribute can raise a compile-time warning. For native/COM code, declare it via header comments and release notes, and state the planned removal date explicitly. The key is committing to an actual date, not a vague “we’ll remove it someday.”
3. Take inventory of callers — build a list of who’s still calling the old API by searching in-house source code, checking installer distribution records, and for COM, checking registry reference usage. If you find a binary you can’t rebuild — a tool built by someone who’s since left, or a third-party app — either extend the old API’s lifetime for that case specifically or bridge the gap with a wrapper.
4. Remove the old API — only after the inventory confirms zero remaining callers, remove it and bump the major version.

This procedure is costly. Which is exactly why, paradoxically, designing a small API with the decision table in mind from the very first release — since anything you never publish carries no compatibility obligation at all — is the single biggest compatibility safeguard you have.

8. Summary

• Think about compatibility in three layers: binary, source, and behavioral. Behavioral compatibility can break even without a rebuild.³
• For native DLLs, adding is safe; changing an existing export, signature, or struct layout is breaking. Give structs a cbSize field to leave room for extension.⁶
• A COM interface is immutable once published. Add changes as a new interface with a new IID (IFoo2) and let callers distinguish via QueryInterface.¹⁴⁷ Enforce this especially strictly whenever early-bound VB6/VBA clients are involved.
• For .NET, you can judge mechanically using the official compatibility change rules. Watch for “apparently safe” changes — adding virtual, renaming a parameter, sealing a type — that are classified as breaking.²
• A realistic three-tier setup: AssemblyVersion carries only the major version, FileVersion tracks the build, and semver declares compatibility.¹⁰
• Semver only works once you declare a public API and a definition of a breaking change.⁵ Adopt the decision table as that definition and check it automatically with tools like Package Validation.¹¹
• When you do break something, go side-by-side offering → deprecation period → inventory → removal. Never swapping things out all at once is what protects the old EXE still running at a client site.

Related Articles

• What Is COM / ActiveX / OCX? — Differences and Relationships Explained Together
• What Is COM — Why Windows COM’s Design Still Holds Up Today
• Calling a Typed .NET 8 DLL From VBA — dscom and TLB
• How Windows DLL Name Resolution Works — Search Order and SxS
• What Is Reg-Free COM? — Using COM Without Registration
• How to Call a C# Native AOT DLL From C/C++

Related Consulting Areas

Komura Software LLC handles compatibility design for DLLs, COM components, and .NET libraries referenced by other systems; taking inventory of public APIs and putting versioning policy in place; and designing and implementing extensions — the IFoo2 pattern, side-by-side offering — that don’t break existing clients.

• Legacy Asset Reuse & Migration Support
• Modification & Maintenance of Existing Windows Software
• Technical Consulting & Design Review
• Contact

References

Related Articles

Recent articles sharing the same tags. Deepen your understanding with closely related topics.

Related Topics

These topic pages place the article in a broader service and decision context.

Where This Topic Connects

This article connects naturally to the following service pages.

Frequently Asked Questions

Common questions about the topic of this article.

If I only add a function to a DLL, do callers need to be rebuilt?

As a rule, no — if you only add an exported function, existing callers keep working as-is, because import resolution still succeeds as long as you don't change an existing function's name, signature, calling convention, or export ordinal. That said, if you add a member to a struct that the caller allocates and passes in, or change the meaning of an existing function's return value or error code, behavioral compatibility can break even though nothing forces a rebuild. The baseline rule is: adding a function is safe, changing an existing signature is breaking.

Why is it forbidden to add a method to a COM interface after it has shipped?

Because under the COM specification, an interface is immutable once it has been published. An interface's real substance is a binary layout contract — the vtable, an ordered list of function pointers — and inserting, removing, or reordering methods means an old binary calls a different method at the slot position it baked in at compile time. Appending to the end doesn't move existing slots, but it introduces a new hazard: a new client can grab an old component instance and assume the appended method is present, then call a slot that doesn't actually exist there. That's why even an append under the same IID isn't allowed. When you want to add functionality, you add a new interface with a new IID (IFoo2) and leave the existing IFoo untouched. Callers can then safely determine, at run time via QueryInterface, whether they're talking to the old interface or the new one.

How should I use .NET's AssemblyVersion, FileVersion, and InformationalVersion differently?

AssemblyVersion is the only version the runtime uses to identify and load an assembly; for strong-named assemblies, .NET Framework's CLR demands an exact match, so bumping it forces callers to add a binding redirect. That's why official guidance suggests reflecting only the major version in AssemblyVersion. FileVersion only shows up in Explorer's file properties and has no effect on runtime behavior, which makes it a good place to stamp in a CI build number. InformationalVersion is a free-form, human-facing string, used to record a semver-formatted version or a commit hash.

Does adopting semantic versioning (semver) solve compatibility problems by itself?

No, semver alone doesn't solve it. Semver is the convention of bumping the major version whenever you make a backward-incompatible change, but it presupposes that you've already declared what counts as your public API and what counts as a breaking change. Slap version numbers on releases without that definition, and the judgment call varies from person to person and the scheme stops working. Semver only becomes meaningful once you adopt something like this article's decision table (for native DLLs) or Microsoft's compatibility change rules (for .NET) as your own definition of a breaking change, and bake that definition into your release process.

Author Profile

Profile page for the article author.

Go Komura

Representative of KomuraSoft LLC

Focused on Windows software development, technical consulting, and investigations into failures that are difficult to reproduce.