The offline feed and the restore
The SDK on this machine has the reference assemblies of Microsoft.NETCore.App and Microsoft.AspNetCore.App in its own packs folder. It has none for the Windows Desktop runtime: those arrive as a NuGet package, Microsoft.WindowsDesktop.App.Ref, and the restore is the step that puts them on disk. On a machine with a network the restore fetches the package from nuget.org. In the container of this course there is no fetch to rely on, so the package sits in a folder that a nuget.config names as a source: a folder feed.
The targeting pack
The feed is one file. The values below are the file the course builds with:
-rw-r--r-- 1 agent agent 7717069 Nov 21 15:42 microsoft.windowsdesktop.app.ref.10.0.15.nupkg
648517d72a772bc461be25ef637bba3c689de426ef71f73cff4b4c1cd63a77a6 microsoft.windowsdesktop.app.ref.10.0.15.nupkg
Seven and a half megabytes, 286 files and about 62 megabytes unpacked. It is the reference assembly pack, not the runtime: it carries the .dll files the compiler reads, with no implementation, which is why a build needs it and a run does not.
The version matters. 10.0.15 matches the runtime of the same version, and a project that asks for another patch version of net10.0-windows resolves the pack the SDK knows about. The SHA-256 is worth keeping: a corrupt download fails the restore with a hash mismatch, and comparing the value is one command.
The nuget.config
A nuget.config next to the project file applies to that project.
<configuration>
<packageSources>
<clear />
<add key="local" value="/work/external/winforms-nuget" />
</packageSources>
</configuration>
Two consequences are worth stating. The restore is offline and fast: with the package in the cache the build of a page's program takes about three seconds. And nothing else can be restored in that project, which is why this course uses no NuGet package beyond the pack: a third-party grid or theme would need a source that this configuration deliberately does not have.
The tools of the course read the folder from one place, so a machine that keeps the feed elsewhere builds the same pages. The environment variable is WINFORMS_NUGET_FEED and its default is /work/external/winforms-nuget; the checker takes --nuget-feed DIR.
A build from the feed
The program of lesson 001 builds with that configuration:
using System;
using System.Windows.Forms;
internal static class Program
{
[STAThread]
private static void Main()
{
ApplicationConfiguration.Initialize();
Application.Run(new Form { Text = "Hello, WinForms" });
}
}
dotnet build app.csproj
Build succeeded.
0 Warning(s)
0 Error(s)
The first build of a page restores the pack, the later ones read it from the package cache under ~/.nuget/packages. The restore is the step that can fail, and its errors have codes of their own: NU1101 for a package no source has, NU1301 for a source that cannot be reached.
Without the feed
A project with a nuget.config that names an empty folder has no source with the pack. To make sure a cached copy does not hide the problem, the command also sends the restore to an empty package folder:
<configuration>
<packageSources>
<clear />
<add key="empty" value="/tmp/empty-feed" />
</packageSources>
</configuration>
dotnet build app.csproj -p:RestorePackagesPath=/tmp/empty-packages
error NU1101: Unable to find package Microsoft.WindowsDesktop.App.Ref. No packages exist with this id in source(s): empty
The real line begins with the full path of the project file and : before error; the message after it is verbatim. The error names the source it searched, which is the fastest way to see that a nuget.config is not the one you think: a project picks up the nearest file up the folder tree, and
A restore that cannot reach nuget.org at all gives NU1301 instead, on the source rather than on the package. Both are restore errors and both stop the build before a single line is compiled.
Where the file comes from
On a machine with a network the file is one download, and there are three routes to it. dotnet restore fetches it on its own when the project targets net10.0-windows; nuget install Microsoft.WindowsDesktop.App.Ref -Version 10.0.15 -OutputDirectory feed fills a folder feed from the command line; and a browser takes the .nupkg from nuget.org. After that the folder is copied to the machine that builds offline, and the nuget.config above points at it. Nothing else is needed: there is no installer and no environment variable to set, which is why a Windows build machine with a full SDK usually has the pack already and never sees this step.
Exercises
- Point the nuget.config at a folder that does not exist and read the error of the restore.
- Remove the .nupkg from the feed folder, clear the package cache entry and see the same NU1101.
- Find the version of the pack the SDK would ask for on a machine with a network and compare it with 10.0.15.
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
Which package carries the reference assemblies of the Windows Desktop runtime?
Answer
Microsoft.WindowsDesktop.App.Ref
The pack is a NuGet package, and its version matches the runtime version.
-
What does <clear /> in the packageSources section do?
Answer
Removes every inherited source, including nuget.org
Only the sources listed after it are used, which makes the restore offline and reproducible.
-
Which error does a package that no source has produce?
Answer
NU1101
NU1101 means the package was not found in any source; NU1301 is a source that could not be reached.
-
Which error does an unreachable source produce?
Answer
NU1301
The restore reports the source it could not load, not a missing package.
-
Why does the course keep the targeting pack instead of the runtime?
Answer
The compiler needs the reference assemblies, and the program is not run here
A .Ref pack has the signatures and no implementation; a build needs exactly that.
-
Which environment variable names the feed folder for the course tools?
Answer
WINFORMS_NUGET_FEED
The scaffold writes that path into the nuget.config of every block.
-
Why does the missing-feed command also pass RestorePackagesPath?
Answer
So a copy in the package cache cannot hide the missing feed
With an empty package folder the restore has to use a source, and the only source is empty.
-
Which nuget.config does a project use?
Answer
The nearest one up the folder tree
NuGet walks up from the project folder and merges, unless a file clears the inherited sources.
-
What does the SHA-256 of the .nupkg prove?
Answer
That the file is the one expected, byte for byte
A hash mismatch means a corrupt or different file, which the restore refuses.
-
What can a project with this nuget.config not restore?
Answer
Any package that is not in the folder feed
The clear element leaves one source, so a third-party package has nowhere to come from.
Every listing on this page was built with the .NET SDK 10.0.303 for net10.0-windows against the targeting pack Microsoft.WindowsDesktop.App.Ref 10.0.15 from the offline feed, in a Docker container on Alpine Linux 3.24.3 (x86_64). The programs were built, not run on Linux: WinForms needs Windows.
Article author: Arthur Isaev