Proposed API for symbolic links

[carlreinke]

Edit by @carlossanlop: Revisited API Proposal

---

---

Original proposal:

Rationale

The ability to interact with symbolic links (symlinks) in .NET is currently limited to determining that a file is ReparsePoint. This proposed API provides the ability to identify, read, and create symbolic links.

Proposed API

public class Directory
{
    public static DirectoryInfo CreateSymbolicLink(string linkPath, string targetPath);
    public static string GetSymbolicLinkTargetPath(string linkPath);
    public static bool IsSymbolicLink(string path);
}

public class File
{
    public static FileInfo CreateSymbolicLink(string linkPath, string targetPath);
    public static string GetSymbolicLinkTargetPath(string linkPath);
    public static bool IsSymbolicLink(string path);
}

public class FileSystemInfo
{
    public bool IsSymbolicLink { get; }
    public string SymbolicLinkTargetPath { get; }

    public void CreateSymbolicLink(string linkPath);
}

Details

The path returned from GetSymbolicLinkTargetPath(string)/SymbolicLinkTargetPath will be returned exactly as it is stored in the symbolic link. It may reference a non-existent file or directory.

For the purposes of this API, NTFS Junction Points are considered to be like Linux bind mounts and are not considered to be symbolic links.

Updates

• Move GetSymbolicLinkTargetPath and IsSymbolicLink from Path to Directory, DirectoryInfo, File and FileInfo.
• Add CreateSymbolicLink.
• Split from Proposed API for canonical paths #23871.
• Change path to linkPath where a link file's path is desired.
• Move the APIs to the FileSystemInfo base class.

[JeremyKuhne]

Adding support for symbolic links is particularly important now that Windows has changed the default permissions for creating them. (In the Fall Creator's Update you no longer need to be elevated to create them)

MSDN Symbolic Links

One of my concerns is how we introduce support for junctions, mounts, or possibly Mac aliases. Would we want to be more generic here, like GetLinkType(path)? There is an immediate need to filter both Junctions and Symbolic links from other reparse point types on Windows. I'm also wondering if we really want to add this to all of the classes, or just Path. I'm not sure if "link to me" (*Info classes) is that useful?

namespace System.IO
{
    public static class Path
    {
        // Or perhaps GetKnownLinkType()?
        public static LinkType GetLinkType(string path);
        public void CreateSymbolicLink(string linkPath, string targetPath);
    }

    public enum LinkType
    {
         None,
         Symbolic,
         Junction
    }
}

[carlreinke]

As far as I know, symbolic links are the only link type that is available on all platforms that .NET Core targets, which makes them more useful than other link types. I don't see a lot of value in supporting other link types, but perhaps I'm just being short-sighted.

Windows differentiates between file and directory symbolic links, so you can't just have Path.CreateSymbolicLink(string, string). (The target doesn't need to exist, so you couldn't query the target to see what kind of symbolic link to create.)

The *Info methods are for creating a link at the path of the *Info to a given target path, so "link from me". (Similar to *Info.Create().)

[JeremyKuhne]

I don't see a lot of value in supporting other link types, but perhaps I'm just being short-sighted.

I'm not expecting creation to become a priority, but identifying Junctions is important (over all the other reparse points, those two need special treatment when enumerating).

The target doesn't need to exist

I didn't even realize that. Is that case useful to support?

The *Info methods are for creating a link at the path of the *Info to a given target path, so "link from me".

I would think "link to" makes more sense. Creating a FileInfo for the target seems backwards from the way I'd expect people to come at this.

[carlreinke]

The target doesn't need to exist

I didn't even realize that. Is that case useful to support?

If I'm creating an arbitrary directory structure with some links in it, I wouldn't want to have to figure out what order I need to create the file and directories in order to make it work. Unzipping a .zip file with symbolic links in it, for example. (That's hypothetical at this point though — .zip probably doesn't store whether the symlink is to a directory or a file.)

I would think "link to" makes more sense. Creating a FileInfo for the target seems backwards from the way I'd expect people to come at this.

Maybe I'm confused. I would expect that:

• File.CreateSymbolicLink(string, string) would return a FileInfo for the symbolic link file that was created.
• FileInfo.CreateSymbolicLink(string) would create a symbolic link file at FileInfo.FullName that targets the path provided in the argument.

[omariom]

How does PowerShell handle links?

[JeremyKuhne]

@carlreinke Sorry I haven't responded, I've been out on an extended vacation. @jhudsoncedaron is also interested in this area and has opened #24655. We should leverage the interest here and try and get a strong proposal together that we can easily clear through API review.

If I'm creating an arbitrary directory structure with some links in it, I wouldn't want to have to figure out what order I need to create the file and directories in order to make it work.

Agreed, thanks for the example.

Maybe I'm confused.

Sorry, terminology is a little weird and I think I was confusing myself. "Create a symbolic link to me" is what I meant, which is what you're describing I think.

[jhudsoncedaron]

I hate to disappoint you guys but "create a directory structure with some links in it" is a pill on Windows because Windows decided to demand knowing whether the target is a file or a directory at create time.

[JeremyKuhne]

"create a directory structure with some links in it" is a pill on Windows because Windows decided to demand knowing whether the target is a file or a directory at create time.

Yeah, not sure why that is- I'll take a look and see if I can find any clues, but I suspect it has some compelling legacy reason that no longer applies.

[JeremyKuhne]

I'm marking this one ready for review with one tweak:

public class DirectoryInfo
{
    // Create a symbolic link at the given path to this directory info
    public void CreateSymbolicLink( string path );
}

public class FileInfo
{
    // Create a symbolic link at the given path to this file info
    public void CreateSymbolicLink( string path );
}

Info classes can be created for non-existent paths. We will allow creating symbolic links at the given path regardless of the info existence if the OS/FileSystem allows it.

[carlreinke]

It seems to me that it's inconsistent if

• FileInfo.Create() creates a file at FileInfo.FullPath and
• FileInfo.CreateSymbolicLink( string ) does not create a (symlink) file at FileInfo.FullPath.

(And similarly for DirectoryInfo.)

[jhudsoncedaron]

@carlreinke : There's a bunch of other problems with this API scheme leading me to have to abandon hope of correcting it.

[JeremyKuhne]

It seems to me that it's inconsistent

@carlreinke I don't think it's a problem, but I'll bring it up at the review. I think it is more of an issue to have IsSymbolicLink change values.

There's a bunch of other problems with this API scheme

@jhudsoncedaron Can you please articulate issues with these specific additional API's here so we can consider them.

I spoke with @pjanotti and we believe that we should be using linkPath and targetPath for additional clarity.

I'm updating the main comment to reflect the discussion.

[jhudsoncedaron]

@JeremyKuhne : It expects the caller to follow links one at a time. To work correctly, the caller must pass an argument to the constructor that specifies whether to get information about the link or the target of the link. It is context sensitive which one the caller would want.

Also, the results of getting one needs to know if its some strange type of file node or not. We probably don't need to handle fifos, block specials, etc. but we at least need to allow directory walking algorithms to know if they encountered one so they can skip over it.