A .NET library that encapsulates OS and filesystem differences for creating Copy-on-Write file links. For release notes see https://github.com/Microsoft/CopyOnWrite#release-history .
$ dotnet add package CopyOnWriteNote: This library is being superseded by CoW support now built into the Windows 11 24H2 release, as well as Windows Server 2025. Use of CoW is automatic for Dev Drive and ReFS volumes starting in these OS versions. See related notes in our blog entry and linked earlier articles. We will continue to accept bug fixes for this library, and updates for the related Microsoft.Build.CopyOnWrite and Microsoft.Build.Artifacts SDKs to use newer versions.
The CopyOnWrite library provides a .NET layer on top of Windows OS-specific logic that provides copy-on-write linking for files (a.k.a. CoW, file cloning, or reflinking). CoW linking provides the ability to copy a file without actually copying the original file's bytes from one disk location to another. The filesystem is in charge of ensuring that if the original file is modified or deleted, the CoW linked files remain unmodified by lazily copying the original file's bytes into each link. Unlike symlinks or hardlinks, writes to CoW links do not write through to the original file, as the filesystem breaks the link and copies in a lazy fashion. This enables scenarios like file caches where a single copy of a file held in a content-addressable or other store is safely linked to many locations in a filesystem with low I/O overhead.
*NOTE: Only Windows functionality is implemented. On Linux and Mac using File.Copy is sufficient as it automatically uses CoW for Linux (starting in .NET 7, and as long as a CoW compatible filesystem like btrfs is in use) and Mac (.NET 8). A similar PR for Windows did not make it into .NET, however there is work underway to integrate CoW into the Windows API in a possible future release.
This library allows a .NET developer to:
Discovery is important, as different operating systems and different filesystems available for those operating systems provide varying levels of CoW link support:
When using this library you may need to create a wrapper that copies the file if CoW is not available.
using Microsoft.CopyOnWrite;
ICopyOnWriteFilesystem cow = CopyOnWriteFilesystemFactory.GetInstance();
bool canCloneInCurrentDirectory = cow.CopyOnWriteLinkSupportedInDirectoryTree(Environment.CurrentDirectory);
if (canCloneInCurrentDirectory)
{
cow.CloneFile(existingFile, cowLinkFilePath);
}File clones on Windows do not actually allocate space on-drive for the clone. This has a good and a possibly bad implication:
CloneFile as the implementation did not use overlapped I/O anyway. CoW support is releasing in the Server 2025 and Win11 24H2 wave, built into the CopyFile API suite and on by default for Dev Drive and ReFS, so overlapped I/O in this library will never be implemented. Resolves https://github.com/microsoft/CopyOnWrite/issues/50CopyOnWriteLinkSupported... methods to avoid the need for checking for Windows OS before calling.CloneFlags.NoSerializedCloning and the useCrossProcessLocksWhereApplicable flag to CopyOnWriteFilesystemFactory. The related concurrency bug in Windows was fixed in recent patches and retested on Windows 11.CloneFlags.DestinationMustMatchSourceSparseness was used (https://github.com/microsoft/CopyOnWrite/issues/17)CloneFlags.NoSparseFileCheck with DestinationMustMatchSourceSparseness,
hence minor version increase.Microsoft.Build.Artifacts MSBuild SDK plugin to speed up file copies for artifact staging.This project welcomes contributions and suggestions. See CONTRIBUTING.md.
If you have a local ReFS drive volume on which to run ReFS related tests, set the following user or system level environment variable:
CoW_Test_ReFS_Drive=D:\
(You may need to exit and restart VS, VSCode, or consoles after setting this.) When this env var is not available, unit tests create and mount a local ReFS VHD for testing and must be run elevated (as admin), e.g. by opening Visual Studio as an admin before opening the solution.
See benchmark data.