[API Proposal]: Creating an empty temporary directory

[eerhardt]

Background and motivation

When dealing with temporary files, especially with more than one, we would like to create our own folder and place them inside. There are several ways to achieve this but for convenience and for completion of the existing Path.GetTempFileName there should be an official API for this.

This has been requested a few times before (#2048, #23538, #31243). #2048 is a large higher-level API proposal for an object model of working with temporary files. To make forward progress here, for 7.0 we should add a simple API that creates a new, empty temp directory. This would correspond with other Unix POSIX work we've been doing in 7.0 (#68770, #67837).

On Unix, this would use mkdtemp, just like how Path.GetTempFileName uses mkstemps. On Windows, this API would generate a new random directory name (possibly using Guid.NewGuid) guaranteeing that the new directory was freshly created.

API Proposal

namespace System.IO;

public static class Path
{
    public static string GetTempPath();
    public static string GetTempFileName();

+    /// <summary>
+    /// Creates a uniquely named, empty directory and returns the full path of that directory. 
+    /// </summary>
+    public static string CreateTemporaryDirectory();
}

API Usage

string tempDirectory = Path.CreateTemporaryDirectory();

File.WriteAllText(Path.Combine(tempDirectory, "file1.txt"), "First file");
File.WriteAllText(Path.Combine(tempDirectory, "file2.txt"), "Second file");

// do something with file1.txt and file2.txt

Directory.Delete(tempDirectory, recursive: true);

Open Questions

1. Should CreateTemporaryDirectory optionally take a string prefix? mkdtemp allows for prefixes. It would allow for libraries/components to "group" their temp directories together in case users need to find them for some reason.

2. Should it return DirectoryInfo instead of string? No other methods in Path deal with FileInfo and DirectoryInfo.

3. We could put it on Directory.CreateTemporaryDirectory() instead of Path - but Path is where GetTempPath and GetTempFileName is. It would be hard to justify putting it in a separate class from the rest of the "temp" methods.

Alternative Designs

Alternatively we could create a full blown TemporaryDirectory class as proposed in #2048. However, that API can be built on top of this one in the future. Adding this lower-level API separately allows for new code to start using it now.

Risks

No response

Tagging subscribers to this area: @dotnet/area-system-io
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

When dealing with temporary files, especially with more than one, we would like to create our own folder and place them inside. There are several ways to achieve this but for convenience and for completion of the existing Path.GetTempFileName there should be an official API for this.

This has been requested a few times before (#2048, #23538, #31243). #2048 is a large higher-level API proposal for an object model of working with temporary files. To make forward progress here, for 7.0 we should add a simple API that creates a new, empty temp directory. This would correspond with other Unix POSIX work we've been doing in 7.0 (#68770, #67837).

On Unix, this would use mkdtemp, just like how Path.GetTempFileName uses mkstemps. On Windows, this API would generate a new random directory name (possibly using Guid.NewGuid) guaranteeing that the new directory was freshly created.

API Proposal

namespace System.IO;

public static class Path
{
    public static string GetTempPath();
    public static string GetTempFileName();

+    /// <summary>
+    /// Creates a uniquely named, empty directory on disk and returns the full path of that directory. 
+    /// </summary>
+    public static string GetTempDirectoryName();
}

API Usage

string tempDirectory = Path.GetTempDirectoryName();

File.WriteAllText(Path.Combine(tempDirectory, "file1.txt"), "First file");
File.WriteAllText(Path.Combine(tempDirectory, "file2.txt"), "Second file");

// do something with file1.txt and file2.txt

Directory.Delete(tempDirectory, recursive: true);

Alternative Designs

Alternatively we could create a full blown TemporaryDirectory class as proposed in #2048. However, that API can be built on top of this one in the future. Adding this lower-level API separately allows for new code to start using it now.

Risks

No response

Author:	eerhardt
Assignees:	-
Labels:	api-suggestion, area-System.IO
Milestone:	7.0.0

[AaronRobinsonMSFT]

This is a difficult problem and security makes things even more complicated. The gist here is any random path doesn't mean it exists after it is returned nor what it may or may not point at.

Alternatively we could create a full blown TemporaryDirectory class as proposed in #2048. However, that API can be built on top of this one in the future. Adding this lower-level API separately allows for new code to start using it now.

I don't think this API can built in a secure way. Having a TemporaryDirectory class that holds onto a handle to ensure it remains what was temporarily created is needed.

[stephentoub]

I wonder if the similarity between Path.GetTempPath() and Path.GetTempDirectoryName() would lead someone to call the latter when they'd intended to call the former (e.g. "Hmm, I need to put something in temp... what's the name of the temp directory? Oh, look, I'll call Path.GetTempDirectoryName to get it"). Maybe that'd be a good thing, except it also wouldn't be idempotent, and so calling it multiple times would likely lead them to a bad place. I think offline you'd suggested a Create prefix... that might be better, even though it diverges from GetTempFileName.

[jozkee]

On Windows, this API would generate a new random directory name (possibly using Guid.NewGuid)

I guess you can use Path.GetRandomFileName() rather than a GUID.

[eerhardt]

I think offline you'd suggested a Create prefix... that might be better, even though it diverges from GetTempFileName.

I went back and forth on using Create, or being consistent with GetTempFileName. I think your comment pushed me to be fully behind using Create in the name. It is just the better name, even if it is inconsistent with GetTempFileName.

I guess you can use Path.GetRandomFileName() rather than a GUID.

It would be shorter - GUIDs are 32 characters long, GetRandomFileName is 12 (8 + . + 3). So the odds of conflicting are higher, but that just means we will need to run the loop more often, even though it is pretty unlikely to conflict.

---

One other question that has come up is: should this return a DirectoryInfo, like Directory.CreateDirectory does. Nothing else in the Path class does, it just talks in terms of string. But I wanted to raise the question.

Another alternative is we could put it on Directory.CreateTemporaryDirectory() instead of Path - but Path is where GetTempPath and GetTempFileName is. It would be hard to justify putting it in a separate class from the rest of the "temp" methods.

[Clockwork-Muse]

empty directory on disk

Linux especially (unsure about Windows) the default temp directory is a tmpfs filesystem, which is ram-backed (although pages out to disk as required). We should probably avoid mentioning anything about "disk" in this context, because presumably it's going to go wherever the currently configured temp directory is.

[deeprobin]

If we use a Guid, I think NewGuid is a wrong option.

NewGuid tries to generate a cryptographically secure random Guid.
Performance-wise this would not be fatal compared to a "normal" random, but I think with such IO topics you have to keep the performance high.
E.g. if many temporary folders have to be created.

I created several times ago a proposal for creating a Non cryptographical Guid for ex. #65736.
See also #22721

[eerhardt]

I guess you can use Path.GetRandomFileName() rather than a GUID.

If we use a Guid, I think NewGuid is a wrong option.

On my windows machine, I'm not seeing much of a performance difference in the following benchmark between doing Guid.NewGuid and Path.GetRandomFileName:

[MemoryDiagnoser]
public class CreateTemporaryDirectoryBenchmark
{
    [Benchmark]
    public void CreateTemporaryDirectory()
    {
        var path = Path.CreateTemporaryDirectory();
        Directory.Delete(path);
    }
}

Method	Toolchain	Mean	Error	StdDev	Ratio	RatioSD	Allocated
CreateTemporaryDirectory	guid	212.3 us	4.19 us	4.30 us	1.00	0.00	648 B
CreateTemporaryDirectory	random	214.7 us	10.64 us	11.39 us	1.01	0.05	568 B

The extra allocation is due to Guid being 32 characters vs random file name being only 12.

You can see the implementation difference between these two in: 028637e

[terrajobst]

• We believe Path.GetTempFileName() was a mistake (should have been called Path.CreateTempFileName())
  • Not bad enough to obsolete, but let's at least hide it
• We'd prefer dedicated APIs on File and Directory
  • We believe customizing the prefix and extension (suffix) for files is desirable.
  • We should disallow path separators for both prefix and suffix

namespace System.IO;

public static class Path
{
    // Existing:
    // public static string GetTempPath();
    // public static string GetTempFileName();

    [EditorBrowsable(EditorBrowsableState.Never)]
    public static string GetTempFileName();
}

public partial class File
{
    public static FileInfo CreateTempFile(string? prefix = null, string? suffix = null);
}

public partial class Directory
{
    public static DirectoryInfo CreateTempSubdirectory(string? prefix = null);
}