NuGet makes it easy for .NET developers to add libraries and update dependencies, but accepting a newly published package version immediately can introduce supply-chain risks. A package may be released before its maintainers or the wider community have had enough time to identify problems with it.
To address this concern, .NET 11 RC 2 introduces command-line support for configuring a minimum package publication age in NuGet package sources. Developers can use this setting to establish a cooldown period before newly published package versions become eligible for selection by supported package-management commands.
The feature is useful for development teams that want more control over dependency updates without manually maintaining every package version. It also provides a configuration option that can be shared across developer machines and continuous integration environments.
In this article, we will explore how the package-age setting works, how to configure it through the .NET CLI, how it affects package updates, and what teams should consider before adopting it in production projects.
What Is a NuGet Package-Age Rule?
A NuGet package-age rule defines how long a package version must have been published before it becomes eligible for selection under the configured policy.
For example, suppose a library maintainer publishes version 3.2.0 today. If your NuGet source has a minimum publication age of 48 hours, that version will not be eligible for selection by package commands that honor the configured cooldown until it satisfies the age requirement.
This delay provides time for maintainers, security researchers, and automated systems to identify problems before the version enters your dependency update workflow.
.NET 11 RC 2 adds the --min-publish-age-hours option to the dotnet nuget add source and dotnet nuget update source commands. The option configures the minPublishAgeHours setting in nuget.config.
The feature also affects supported package selection operations performed by dotnet package add and dotnet package update. When an update excludes a newer version because it does not meet the configured age requirement, the command reports that information.
The policy is not a guarantee that an older package is secure. It is a time-based control that complements existing dependency management practices.
Why Package Publication Age Matters
Modern .NET applications often depend on dozens or hundreds of direct and transitive NuGet packages. Each dependency introduces a potential point of failure if a package contains malicious code, an accidental regression, or an unexpected behavior change.
A newly published version may be completely legitimate, but it has had less time to be evaluated by users and automated systems.
A package-age policy introduces a deliberate delay between publication and eligibility.
Reduce Exposure to Newly Published Packages
A short cooldown can reduce the chance that an application automatically selects a problematic version immediately after publication.
For example, a team using floating package versions may otherwise receive a newer matching version during a routine dependency update. A configured age requirement can exclude versions that are too recent.
Improve Dependency Update Control
Organizations can establish a consistent policy instead of relying on every developer to decide independently when a package should be updated.
This is particularly useful when package updates are automated and reviewed through pull requests.
Support Supply-Chain Security
Package-age rules can form one part of a broader dependency security strategy. They work alongside vulnerability scanning, package source restrictions, dependency review, and lock files.
However, a cooldown does not verify package ownership, inspect source code, or prove that a package has no vulnerabilities.
How to Configure a Minimum Package Age
The configuration is performed through the NuGet CLI commands included in the .NET 11 RC 2 tooling.
Step 1: Identify the NuGet Configuration File
NuGet settings can be defined in configuration files at different levels. For a repository-specific policy, a nuget.config file in the repository is often a practical choice.
A repository-level configuration makes the intended policy easier to review and share with the development team.
First, confirm that your project uses the intended .NET 11 RC 2 SDK.
dotnet --info
Check the reported SDK version before proceeding. An older SDK might not recognize the new command-line option.
Step 2: Add a NuGet Source With a Cooldown
The following command adds the public NuGet source with a 24-hour minimum package publication age:
dotnet nuget add source \
https://api.nuget.org/v3/index.json \
--name public \
--min-publish-age-hours 24 \
--configfile nuget.config
The options have the following purposes:
add source registers a package source.
--name public assigns a name to the source.
--min-publish-age-hours 24 establishes a 24-hour cooldown.
--configfile nuget.config specifies the configuration file to update.
Use the source name that matches your repository's existing configuration. If the source is already configured, update it rather than creating an unnecessary duplicate.
Step 3: Update an Existing Source
Suppose your repository already has a source named public and your team wants to increase the cooldown to 48 hours.
Run:
dotnet nuget update source public \
--min-publish-age-hours 48 \
--configfile nuget.config
This updates the source's package-age setting in the specified configuration file.
The choice between 24 and 48 hours is a policy decision, not a universal security recommendation. Teams should select a duration that balances their release requirements with their tolerance for newly published dependencies.
Step 4: Review the Configuration
After running the command, inspect the resulting nuget.config file.
The relevant source configuration includes the minPublishAgeHours setting. For example, a source configured with a 48-hour cooldown can contain an entry similar to this:
<?xml version="1.0" encoding="utf-8"?>
<configuration>
<packageSources>
<add key="public"
value="https://api.nuget.org/v3/index.json"
minPublishAgeHours="48" />
</packageSources>
</configuration>
This XML illustrates the relevant setting in a simplified configuration file. Preserve any existing credentials, mappings, package sources, and other configuration required by your project.
The important point is that the CLI writes the policy into NuGet configuration rather than requiring developers to edit the XML manually.
How the Cooldown Affects Package Updates
A configured cooldown influences which package versions are eligible for selection by supported package commands.
Consider a project that uses a floating version range to select compatible updates. If a matching package version was published too recently, the package-selection operation can exclude it and consider another eligible version.
For example, a team might use a package reference that allows updates within a major version:
<ItemGroup>
<PackageReference Include="Example.Library"
Version="3.*" />
</ItemGroup>
This is an illustrative package reference, not a requirement to use floating versions. Floating version ranges allow NuGet to select a matching version according to the applicable rules.
With a package-age cooldown, a newly published matching version may be excluded until it becomes old enough.
What Happens When No Version Is Eligible?
The cooldown can create a conflict when a project uses floating versions and no matching version satisfies the age requirement.
In this situation, .NET 11 RC 2 reports error NU1020 during restore rather than silently allowing a no-op restore to conceal the conflict.
This behavior is important for CI pipelines because a failed restore makes the configuration issue visible. Developers can investigate the available versions, the configured cooldown, and the project's version constraints.
Do not resolve this error by automatically disabling the policy. First determine whether the package is genuinely required and whether the current dependency range allows an appropriate alternative.
Best Practices for Production Projects
1. Apply the Policy Consistently
Store the repository's NuGet configuration in source control when appropriate. Ensure that local development and CI environments use the intended configuration.
Be aware that NuGet configuration can be inherited from different levels. Check the effective configuration rather than assuming that a repository file is the only source of settings.
2. Start With a Policy That Fits Your Release Cycle
A longer cooldown can reduce exposure to very recent package releases, but it can also delay access to legitimate fixes.
Choose the duration based on your release frequency, dependency update process, and security requirements. Test the policy before applying it to every production repository.
3. Continue Scanning for Vulnerabilities
Package age is not a vulnerability scanner.
An older version can contain a known security flaw, while a newly published version can contain an important security fix. Continue using vulnerability checks and review dependency advisories when deciding whether to update a package.
4. Review Dependency Updates Before Merging
Use pull requests to make dependency changes visible to reviewers. Inspect version changes, release notes, compatibility implications, and test results.
For important applications, validate the update in CI before merging it into the production branch.
5. Document Exceptions
Some applications need urgent package updates to address security incidents or production defects.
Define an exception process that allows authorized developers to respond to urgent issues without silently weakening the dependency policy for every project.
Advantages and Disadvantages
Advantages
Reduced exposure to very recent releases: The cooldown prevents eligible package-selection commands from choosing versions that are too new.
CLI-based configuration: Developers can configure the policy through supported NuGet source commands instead of editing XML manually.
Consistent team policies: A repository configuration can help align local development and automated build environments.
Clearer update behavior: The tooling reports when a newer version is excluded and surfaces certain floating-version conflicts.
Disadvantages
Delayed updates: The cooldown can prevent a legitimate new release from being selected immediately.
Configuration management: Teams must ensure that the intended NuGet configuration is used across environments.
No security guarantee: Waiting does not prove that a package is safe or free from vulnerabilities.
Potential restore failures: A restrictive cooldown can leave no eligible version for a floating package reference.
Common Mistakes and Troubleshooting
The CLI Does Not Recognize the Option
Verify that the installed SDK and NuGet tooling support --min-publish-age-hours. Use the intended .NET 11 RC 2 SDK and inspect the command's help output if necessary.
The Setting Does Not Affect the Expected Package
Confirm that the package source being used has the cooldown configured. Also verify that the package-management operation supports the setting and that the correct nuget.config file is being loaded.
Restore Fails With NU1020
Inspect the floating version range and available matching package versions. Determine whether the cooldown excludes all eligible versions.
If necessary, revise the dependency range or follow the organization's documented exception process.
A Security Fix Is Delayed
Review the urgency of the fix and the package's release information. Apply the organization's emergency dependency update process where justified rather than treating package age as an absolute rule.
Summary
.NET 11 RC 2 introduces a practical way to configure NuGet package publication age through the .NET CLI. The --min-publish-age-hours option lets developers set or update a source's minimum publication age, while supported package commands use that cooldown when selecting versions.
For teams that automate dependency updates, this can add a useful layer of control over newly published packages. However, the policy should complement vulnerability scanning, dependency review, testing, and a clear process for urgent security updates.
Start by configuring the policy in a test repository, verifying the effective NuGet settings, and observing how package selection and restore behave. Once the results are understood, apply the policy consistently across development and CI environments.
Join the conversation! Your thoughts help the community grow.