Fixar dependências NuGet: PackageReference, gerenciamento central de pacotes e packages.lock.json

Objetivo

Cada restore de uma aplicação produz o mesmo fecho de pacotes em qualquer máquina e no CI, e qualquer mudança nas dependências aparece como um diff revisável.

Pré-requisitos

Projetos no estilo SDK que usam PackageReference em vez de packages.config, uma única raiz de repositório e um job de CI que executa dotnet restore como etapa própria.

Passos

1. Entenda as regras listadas na documentação de resolução de dependências: menor versão aplicável (uma referência a 4.0.0 significa pelo menos 4.0.0, e o NuGet escolhe a menor versão que satisfaz todas as restrições), direct-dependency-wins (a dependência direta prevalece) e cousin dependencies (dependências primas). Versões flutuantes como 4.* optam pela correspondência mais recente a cada restore.
2. Concentre as versões em um só lugar: crie Directory.Packages.props na raiz do repositório com <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally> e um <PackageVersion Include="..." Version="..." /> por pacote; os arquivos de projeto mantêm <PackageReference Include="..." /> sem versão. A documentação afirma que apenas o Directory.Packages.props mais próximo é importado automaticamente; por isso, mantenha um único arquivo, a menos que você importe o do diretório pai de forma explícita.
3. Ative o arquivo de lock: defina <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile> (em Directory.Build.props, para valer em todos os projetos) e execute dotnet restore; o NuGet grava um packages.lock.json na raiz de cada projeto, listando o fecho completo, incluindo os pacotes transitivos.
4. Faça commit do arquivo de lock de cada aplicação ou executável que esteja no início de uma cadeia de dependências. Para um projeto de biblioteca do qual outros projetos do repositório dependem, a documentação diz para não versionar o arquivo de lock: o restore do projeto consumidor não o utiliza (a documentação acrescenta que mantê-lo não causa problemas).
5. No CI, restaure com dotnet restore --locked-mode (ou RestoreLockedMode=true): se as dependências declaradas mudaram sem que o lock fosse atualizado, o restore falha em vez de regenerar o arquivo de lock silenciosamente.
6. Para atualizar: altere a versão em Directory.Packages.props, execute dotnet restore sem o modo locked (o NuGet detecta a mudança na entrada e reescreve o arquivo de lock; --force-evaluate só é necessário para avançar uma versão flutuante), revise o diff do lock e faça commit dos dois arquivos juntos.
7. Fixe o SDK com global.json (a documentação cita a política rollForward com valor disable): ela avisa que os itens PackageReference implícitos adicionados pelo SDK mudam conforme a versão do SDK e causam falhas no modo locked.

Resultado esperado

Um clone novo restaura versões idênticas; o git diff de uma atualização mostra exatamente quais pacotes mudaram, inclusive os transitivos; um novo pacote transitivo não consegue entrar no build sem ser notado.

Limites e base de verificação

Versões flutuantes e o modo locked entram em conflito entre si; escolha um dos dois. Vários target frameworks produzem vários conjuntos de dependências em um único arquivo de lock. Arquivos de lock não substituem a fixação de fontes de pacotes em nuget.config nem a verificação de assinaturas. Trata-se de um procedimento documentado; não se afirma nenhuma medição de tempo de restore.