Add support for DeterministicTimestamp

omajid · omajid · commit 19b6b2f2bac0 · 2025-12-29T15:33:24.000-05:00
Add support for a new MSBuild property that developrs can use to
override the deterministic timestamp. This allows developers to override
the auto-computed timetsamps, and enables working around processes/tools
that don't like the fixed/old timetsamps.
diff --git a/src/NuGet.Core/NuGet.Build.Tasks.Pack/IPackTaskRequest.cs b/src/NuGet.Core/NuGet.Build.Tasks.Pack/IPackTaskRequest.cs
@@ -76,6 +76,7 @@ public interface IPackTaskRequest<TItem>
         string PackageLicenseFile { get; }
         string Readme { get; }
         bool Deterministic { get; }
+        string DeterministicTimestamp { get; }
         string PackageIcon { get; }
     }
 }
diff --git a/src/NuGet.Core/NuGet.Build.Tasks.Pack/PackTask.cs b/src/NuGet.Core/NuGet.Build.Tasks.Pack/PackTask.cs
@@ -92,6 +92,7 @@ internal PackTask(IEnvironmentVariableReader environmentVariableReader)
         public string PackageLicenseExpressionVersion { get; set; }
         public string Readme { get; set; }
         public bool Deterministic { get; set; }
+        public string DeterministicTimestamp { get; set; }
         public string PackageIcon { get; set; }
         public ILogger Logger => new MSBuildLogger(Log);
 
@@ -225,6 +226,7 @@ private IPackTaskRequest<IMSBuildItem> GetRequest()
                 PackageLicenseExpressionVersion = MSBuildStringUtility.TrimAndGetNullForEmpty(PackageLicenseExpressionVersion),
                 Readme = MSBuildStringUtility.TrimAndGetNullForEmpty(Readme),
                 Deterministic = Deterministic,
+                DeterministicTimestamp = MSBuildStringUtility.TrimAndGetNullForEmpty(DeterministicTimestamp),
                 PackageIcon = MSBuildStringUtility.TrimAndGetNullForEmpty(PackageIcon),
             };
         }
diff --git a/src/NuGet.Core/NuGet.Build.Tasks.Pack/PackTaskLogic.cs b/src/NuGet.Core/NuGet.Build.Tasks.Pack/PackTaskLogic.cs
@@ -43,6 +43,7 @@ public PackArgs GetPackArgs(IPackTaskRequest<IMSBuildItem> request)
                 NoPackageAnalysis = request.NoPackageAnalysis,
                 NoDefaultExcludes = request.NoDefaultExcludes,
                 Deterministic = request.Deterministic,
+                DeterministicTimestamp = request.DeterministicTimestamp,
                 WarningProperties = WarningProperties.GetWarningProperties(request.TreatWarningsAsErrors, request.WarningsAsErrors, request.NoWarn, request.WarningsNotAsErrors),
                 PackTargetArgs = new MSBuildPackTargetArgs()
             };
@@ -134,6 +135,14 @@ public PackageBuilder GetPackageBuilder(IPackTaskRequest<IMSBuildItem> request)
                 PackageTypes = ParsePackageTypes(request)
             };
 
+            if (request.Deterministic)
+            {
+                if (request.DeterministicTimestamp != null)
+                {
+                    builder.DeterministicTimestamp = request.DeterministicTimestamp;
+                }
+            }
+
             if (request.DevelopmentDependency)
             {
                 builder.DevelopmentDependency = true;
diff --git a/src/NuGet.Core/NuGet.Build.Tasks.Pack/PackTaskRequest.cs b/src/NuGet.Core/NuGet.Build.Tasks.Pack/PackTaskRequest.cs
@@ -71,6 +71,7 @@ public class PackTaskRequest : IPackTaskRequest<IMSBuildItem>
         public string PackageLicenseExpression { get; set; }
         public string PackageLicenseExpressionVersion { get; set; }
         public bool Deterministic { get; set; }
+        public string DeterministicTimestamp { get; set; }
         public string PackageIcon { get; set; }
     }
 }
diff --git a/src/NuGet.Core/NuGet.Build.Tasks/NuGet.Build.Tasks.Pack.targets b/src/NuGet.Core/NuGet.Build.Tasks/NuGet.Build.Tasks.Pack.targets
@@ -279,6 +279,7 @@ Copyright (c) .NET Foundation. All rights reserved.
               PackageLicenseExpressionVersion="$(PackageLicenseExpressionVersion)"
               Readme="$(PackageReadmeFile)"
               Deterministic="$(Deterministic)"
+              DeterministicTimestamp="$(DeterministicTimestamp)"
               PackageIcon="$(PackageIcon)"
               />
   </Target>
diff --git a/src/NuGet.Core/NuGet.Commands/CommandArgs/PackArgs.cs b/src/NuGet.Core/NuGet.Commands/CommandArgs/PackArgs.cs
@@ -45,6 +45,7 @@ public class PackArgs
         public bool Tool { get; set; }
         public string Version { get; set; }
         public bool Deterministic { get; set; }
+        public string DeterministicTimestamp { get; set; }
         public WarningProperties WarningProperties { get; set; }
         public MSBuildPackTargetArgs PackTargetArgs { get; set; }
         public Dictionary<string, string> Properties
diff --git a/src/NuGet.Core/NuGet.Commands/CommandRunners/PackCommandRunner.cs b/src/NuGet.Core/NuGet.Commands/CommandRunners/PackCommandRunner.cs
@@ -446,23 +446,31 @@ private PackageBuilder CreatePackageBuilderFromNuspec(string path)
                 _packArgs.Logger = new PackCollectorLogger(_packArgs.Logger, _packArgs.WarningProperties);
             }
 
+            PackageBuilder result;
+
             if (string.IsNullOrEmpty(_packArgs.BasePath))
             {
-                return new PackageBuilder(
+                result = new PackageBuilder(
                     path,
                     _packArgs.GetPropertyValue,
                     !_packArgs.ExcludeEmptyDirectories,
                     _packArgs.Deterministic,
                     _packArgs.Logger);
             }
+            else
+            {
+                result = new PackageBuilder(
+                    path,
+                    _packArgs.BasePath,
+                    _packArgs.GetPropertyValue,
+                    !_packArgs.ExcludeEmptyDirectories,
+                    _packArgs.Deterministic,
+                    _packArgs.Logger);
+            }
 
-            return new PackageBuilder(
-                path,
-                _packArgs.BasePath,
-                _packArgs.GetPropertyValue,
-                !_packArgs.ExcludeEmptyDirectories,
-                _packArgs.Deterministic,
-                _packArgs.Logger);
+            result.DeterministicTimestamp = _packArgs.DeterministicTimestamp;
+
+            return result;
         }
 
         private bool BuildFromProjectFile(string path)
diff --git a/src/NuGet.Core/NuGet.Commands/PublicAPI/net472/PublicAPI.Shipped.txt b/src/NuGet.Core/NuGet.Commands/PublicAPI/net472/PublicAPI.Shipped.txt
@@ -340,6 +340,8 @@ NuGet.Commands.PackArgs.Build.set -> void
 ~NuGet.Commands.PackArgs.CurrentDirectory.set -> void
 NuGet.Commands.PackArgs.Deterministic.get -> bool
 NuGet.Commands.PackArgs.Deterministic.set -> void
+~NuGet.Commands.PackArgs.DeterministicTimestamp.get -> string
+~NuGet.Commands.PackArgs.DeterministicTimestamp.set -> void
 ~NuGet.Commands.PackArgs.Exclude.get -> System.Collections.Generic.IEnumerable<string>
 ~NuGet.Commands.PackArgs.Exclude.set -> void
 NuGet.Commands.PackArgs.ExcludeEmptyDirectories.get -> bool
diff --git a/src/NuGet.Core/NuGet.Commands/PublicAPI/net8.0/PublicAPI.Shipped.txt b/src/NuGet.Core/NuGet.Commands/PublicAPI/net8.0/PublicAPI.Shipped.txt
@@ -340,6 +340,8 @@ NuGet.Commands.PackArgs.Build.set -> void
 ~NuGet.Commands.PackArgs.CurrentDirectory.set -> void
 NuGet.Commands.PackArgs.Deterministic.get -> bool
 NuGet.Commands.PackArgs.Deterministic.set -> void
+~NuGet.Commands.PackArgs.DeterministicTimestamp.get -> string
+~NuGet.Commands.PackArgs.DeterministicTimestamp.set -> void
 ~NuGet.Commands.PackArgs.Exclude.get -> System.Collections.Generic.IEnumerable<string>
 ~NuGet.Commands.PackArgs.Exclude.set -> void
 NuGet.Commands.PackArgs.ExcludeEmptyDirectories.get -> bool
diff --git a/src/NuGet.Core/NuGet.Packaging/GlobalSuppressions.cs b/src/NuGet.Core/NuGet.Packaging/GlobalSuppressions.cs
@@ -44,7 +44,6 @@
 [assembly: SuppressMessage("Build", "CA1062:In externally visible method 'IEnumerable<string> PackageArchiveReader.CopyFiles(string destination, IEnumerable<string> packageFiles, ExtractPackageFileDelegate extractFile, ILogger logger, CancellationToken token)', validate parameter 'packageFiles' is non-null before using it. If appropriate, throw an ArgumentNullException when the argument is null or add a Code Contract precondition asserting non-null argument.", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageArchiveReader.CopyFiles(System.String,System.Collections.Generic.IEnumerable{System.String},NuGet.Packaging.Core.ExtractPackageFileDelegate,NuGet.Common.ILogger,System.Threading.CancellationToken)~System.Collections.Generic.IEnumerable{System.String}")]
 [assembly: SuppressMessage("Build", "CA1062:In externally visible method 'IEnumerable<ZipFilePair> PackageArchiveReader.EnumeratePackageEntries(IEnumerable<string> packageFiles, string packageDirectory)', validate parameter 'packageFiles' is non-null before using it. If appropriate, throw an ArgumentNullException when the argument is null or add a Code Contract precondition asserting non-null argument.", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageArchiveReader.EnumeratePackageEntries(System.Collections.Generic.IEnumerable{System.String},System.String)~System.Collections.Generic.IEnumerable{NuGet.Packaging.ZipFilePair}")]
 [assembly: SuppressMessage("Build", "CA1062:In externally visible method 'Stream PackageArchiveReader.GetStream(string path)', validate parameter 'path' is non-null before using it. If appropriate, throw an ArgumentNullException when the argument is null or add a Code Contract precondition asserting non-null argument.", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageArchiveReader.GetStream(System.String)~System.IO.Stream")]
-[assembly: SuppressMessage("Build", "CA1801:Parameter deterministic of method .ctor is never used. Remove the parameter or use it in the method body.", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageBuilder.#ctor(System.Boolean,System.Boolean)")]
 [assembly: SuppressMessage("Build", "CA1062:In externally visible method 'void PackageBuilder.AddFiles(string basePath, string source, string destination, string exclude = null)', validate parameter 'source' is non-null before using it. If appropriate, throw an ArgumentNullException when the argument is null or add a Code Contract precondition asserting non-null argument.", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageBuilder.AddFiles(System.String,System.String,System.String,System.String)")]
 [assembly: SuppressMessage("Build", "CA1822:Member GenerateRelationshipId does not access instance data and can be marked as static (Shared in VisualBasic)", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageBuilder.GenerateRelationshipId(System.String)~System.String")]
 [assembly: SuppressMessage("Build", "CA1062:In externally visible method 'void PackageBuilder.Populate(ManifestMetadata manifestMetadata)', validate parameter 'manifestMetadata' is non-null before using it. If appropriate, throw an ArgumentNullException when the argument is null or add a Code Contract precondition asserting non-null argument.", Justification = "<Pending>", Scope = "member", Target = "~M:NuGet.Packaging.PackageBuilder.Populate(NuGet.Packaging.ManifestMetadata)")]
diff --git a/src/NuGet.Core/NuGet.Packaging/PackageCreation/Authoring/PackageBuilder.cs b/src/NuGet.Core/NuGet.Packaging/PackageCreation/Authoring/PackageBuilder.cs
@@ -5,7 +5,6 @@
 
 using System;
 using System.Collections.Generic;
-using System.Collections.Immutable;
 using System.Collections.ObjectModel;
 using System.Diagnostics;
 using System.Globalization;
@@ -30,19 +29,14 @@ namespace NuGet.Packaging
     public class PackageBuilder : IPackageMetadata
     {
         private static readonly Uri DefaultUri = new Uri("http://defaultcontainer/");
-        // The acutal minimum date is January 1, 1980. However, there's no
-        // timezone information stored in zip entries. That can lead to
-        // situations where January 1 local (in the zip file) converts to a UTC
-        // min date that's before 1980, breaking all sorts of things. Add a
-        // margin of 1 day for to avoid this.
-        private static readonly DateTime ZipFormatMinDate = new DateTime(1980, 1, 2, 0, 0, 0, DateTimeKind.Utc);
+        private static readonly DateTime ZipFormatMinDate = new DateTime(1980, 1, 1, 0, 0, 0, DateTimeKind.Utc);
         private static readonly DateTime ZipFormatMaxDate = new DateTime(2107, 12, 31, 23, 59, 58, DateTimeKind.Utc);
+
         internal const string ManifestRelationType = "manifest";
         private readonly IEnvironmentVariableReader _environmentVariableProvider;
-        private readonly bool _includeEmptyDirectories;
         private readonly bool _deterministic;
+        private readonly bool _includeEmptyDirectories;
         private readonly ILogger _logger;
-        private readonly DateTime _deterministicDate;
 
         /// <summary>
         /// Maximum Icon file size: 1 megabyte
@@ -128,7 +122,6 @@ private PackageBuilder(IEnvironmentVariableReader environmentVariableProvider, b
             _environmentVariableProvider = environmentVariableProvider;
             _includeEmptyDirectories = includeEmptyDirectories;
             _deterministic = deterministic;
-            _deterministicDate = ComputeDeterministicDate();
             _logger = logger;
             Files = new Collection<IPackageFile>();
             DependencyGroups = new Collection<PackageDependencyGroup>();
@@ -145,20 +138,6 @@ private PackageBuilder(IEnvironmentVariableReader environmentVariableProvider, b
             Properties = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
         }
 
-        private DateTime ComputeDeterministicDate()
-        {
-            string sourceBuildEpoch = _environmentVariableProvider.GetEnvironmentVariable("SOURCE_DATE_EPOCH");
-            if (sourceBuildEpoch != null &&
-                long.TryParse(sourceBuildEpoch, NumberStyles.None, CultureInfo.InvariantCulture, out long unixTimeSeconds))
-            {
-                return DateTimeOffset.FromUnixTimeSeconds(unixTimeSeconds).UtcDateTime;
-            }
-            else
-            {
-                return ZipFormatMinDate;
-            }
-        }
-
         public string Id
         {
             get;
@@ -285,6 +264,73 @@ public ISet<string> Tags
 
         public string Readme { get; set; }
 
+        private string _deterministicTimestamp;
+        private DateTimeOffset? _finalDeterministicTimestamp;
+
+        public string DeterministicTimestamp
+        {
+            get => _deterministicTimestamp;
+            set
+            {
+                if (_deterministicTimestamp != value)
+                {
+                    _deterministicTimestamp = value;
+                    _finalDeterministicTimestamp = null;
+                }
+            }
+        }
+
+        private DateTimeOffset FinalDeterministicTimestamp
+        {
+            get => _finalDeterministicTimestamp ??= ComputeDeterministicTimestamp();
+        }
+
+        private DateTimeOffset ComputeDeterministicTimestamp()
+        {
+            string sourceBuildEpoch = _environmentVariableProvider.GetEnvironmentVariable("SOURCE_DATE_EPOCH");
+            if (sourceBuildEpoch != null &&
+                long.TryParse(sourceBuildEpoch, NumberStyles.None, CultureInfo.InvariantCulture, out long unixTimeSeconds))
+            {
+                return DateTimeOffset.FromUnixTimeSeconds(unixTimeSeconds);
+            }
+
+            if (DeterministicTimestamp != null)
+            {
+                var parsedDate = ParseRfc3339(DeterministicTimestamp);
+                if (parsedDate is DateTimeOffset nonNullParsedTimestamp)
+                {
+                    return nonNullParsedTimestamp;
+                }
+            }
+
+            return ZipFormatMinDate;
+        }
+
+        private static DateTimeOffset? ParseRfc3339(string input)
+        {
+            // RFC3339 patterns:
+            // 1. Full date-time with 'Z' (UTC)
+            // 2. Full date-time with offset (+HH:mm or -HH:mm)
+            // 3. Full date-time with fractional seconds and 'Z'
+            // 4. Full date-time with fractional seconds and offset
+            string[] formats = {
+                "yyyy-MM-dd'T'HH:mm:ss'Z'",
+                "yyyy-MM-dd'T'HH:mm:sszzz",
+                "yyyy-MM-dd'T'HH:mm:ss.FFFK", // K handles Z or offset
+                "yyyy-MM-dd'T'HH:mm:ss.fffffffK"
+            };
+
+            if (DateTimeOffset.TryParseExact(input, formats,
+                CultureInfo.InvariantCulture,
+                DateTimeStyles.AssumeUniversal | DateTimeStyles.AdjustToUniversal,
+                out DateTimeOffset result))
+            {
+                return result;
+            }
+
+            return null;
+        }
+
         /// <summary>
         /// Exposes the additional properties extracted by the metadata
         /// extractor or received from the command line.
@@ -1028,7 +1074,7 @@ private ZipArchiveEntry CreateEntry(ZipArchive package, string entryName, Compre
             var entry = package.CreateEntry(entryName, compressionLevel);
             if (_deterministic)
             {
-                entry.LastWriteTime = _deterministicDate;
+                entry.LastWriteTime = FinalDeterministicTimestamp;
             }
             return entry;
         }
@@ -1084,7 +1130,7 @@ private SortedSet<string> WriteFiles(ZipArchive package, SortedSet<string> files
                         package,
                         file.Path,
                         stream,
-                        lastWriteTime: _deterministic ? _deterministicDate : file.LastWriteTime,
+                        lastWriteTime: _deterministic ? FinalDeterministicTimestamp : file.LastWriteTime,
                         warningMessage);
                     var fileExtension = Path.GetExtension(file.Path);
 
diff --git a/src/NuGet.Core/NuGet.Packaging/PublicAPI/net472/PublicAPI.Shipped.txt b/src/NuGet.Core/NuGet.Packaging/PublicAPI/net472/PublicAPI.Shipped.txt
@@ -552,6 +552,8 @@ NuGet.Packaging.PackageBuilder
 ~NuGet.Packaging.PackageBuilder.Description.set -> void
 NuGet.Packaging.PackageBuilder.DevelopmentDependency.get -> bool
 NuGet.Packaging.PackageBuilder.DevelopmentDependency.set -> void
+~NuGet.Packaging.PackageBuilder.DeterministicTimestamp.get -> string
+~NuGet.Packaging.PackageBuilder.DeterministicTimestamp.set -> void
 NuGet.Packaging.PackageBuilder.EmitRequireLicenseAcceptance.get -> bool
 NuGet.Packaging.PackageBuilder.EmitRequireLicenseAcceptance.set -> void
 ~NuGet.Packaging.PackageBuilder.Files.get -> System.Collections.Generic.ICollection<NuGet.Packaging.IPackageFile>
diff --git a/src/NuGet.Core/NuGet.Packaging/PublicAPI/net8.0/PublicAPI.Shipped.txt b/src/NuGet.Core/NuGet.Packaging/PublicAPI/net8.0/PublicAPI.Shipped.txt
@@ -552,6 +552,8 @@ NuGet.Packaging.PackageBuilder
 ~NuGet.Packaging.PackageBuilder.Description.set -> void
 NuGet.Packaging.PackageBuilder.DevelopmentDependency.get -> bool
 NuGet.Packaging.PackageBuilder.DevelopmentDependency.set -> void
+~NuGet.Packaging.PackageBuilder.DeterministicTimestamp.get -> string
+~NuGet.Packaging.PackageBuilder.DeterministicTimestamp.set -> void
 NuGet.Packaging.PackageBuilder.EmitRequireLicenseAcceptance.get -> bool
 NuGet.Packaging.PackageBuilder.EmitRequireLicenseAcceptance.set -> void
 ~NuGet.Packaging.PackageBuilder.Files.get -> System.Collections.Generic.ICollection<NuGet.Packaging.IPackageFile>

Original file line number	Diff line number	Diff line change
`@@ -76,6 +76,7 @@ public interface IPackTaskRequest<TItem>`
`76`	`76`	`string PackageLicenseFile { get; }`
`77`	`77`	`string Readme { get; }`
`78`	`78`	`bool Deterministic { get; }`
	`79`	`+ string DeterministicTimestamp { get; }`
`79`	`80`	`string PackageIcon { get; }`
`80`	`81`	`}`
`81`	`82`	`}`
Original file line number	Diff line number	Diff line change
`@@ -71,6 +71,7 @@ public class PackTaskRequest : IPackTaskRequest<IMSBuildItem>`
`71`	`71`	`public string PackageLicenseExpression { get; set; }`
`72`	`72`	`public string PackageLicenseExpressionVersion { get; set; }`
`73`	`73`	`public bool Deterministic { get; set; }`
	`74`	`+ public string DeterministicTimestamp { get; set; }`
`74`	`75`	`public string PackageIcon { get; set; }`
`75`	`76`	`}`
`76`	`77`	`}`