project.json referência

NuGet 3.x

O arquivo project.json mantém uma lista de pacotes usados em um projeto, conhecido como um formato de gerenciamento de pacotes. Ele substitui packages.config mas por sua vez é substituído por PackageReference com o NuGet 4.0+.

O arquivo project.lock.json (descrito abaixo) também é usado em projetos que empregam project.json.

project.json tem a seguinte estrutura básica, onde cada um dos quatro objetos de nível superior pode ter qualquer número de objetos filho:

{
    "dependencies": {
        "PackageID" : "{version_constraint}"
    },
    "frameworks" : {
        "TxM" : {}
    },
    "runtimes" : {
        "RID": {}
    },
    "supports" : {
        "CompatibilityProfile" : {}
    }
}

Migrar project.json para PackageReference

A migração entre project.json e PackageReference é simples.

Migração automática no Visual Studio 2026

O Visual Studio 2026 e posterior migra automaticamente project.json projetos para PackageReference quando você abre uma solução que contém project.json projetos. A migração acontece no momento do carregamento da solução:

1. Abra uma solução que contenha project.json projetos no Visual Studio 2026 ou posterior.
2. O Visual Studio deteta automaticamente project.json arquivos e os migra para o formato PackageReference.
3. Para verificar o status da migração, abra a janela de saída e selecione Mostrar saída do "Gerenciador de pacotes". Você verá mensagens como "Migrando project.json projeto..." seguido de "Migração bem-sucedida" para cada projeto. Quaisquer erros aparecerão na Lista de Erros.
4. Um backup do arquivo de projeto original e project.json arquivo é criado em uma Backup pasta na raiz do diretório do projeto.
5. A migração converte todas as dependências do pacote para o formato PackageReference no arquivo de projeto.

Migração manual no Visual Studio 2022

Para o Visual Studio 2022 e versões anteriores, você pode usar o migrador interno:

1. Carregue o projeto project.json no Visual Studio.
2. Vá para o gerenciador de soluções do projeto project.json e localize o nó dependências.
3. Clique com o botão direito do rato e selecione Migrate project.json to PackageReference...

Métodos alternativos de migração

Como alternativa, você pode usar a ferramenta de linha de comando dotnet migrate ou fazer a migração manualmente pegando todo o conteúdo do arquivo project.json e substituindo-o pela sintaxe PackageReference equivalente.

Dependências

Lista as dependências do pacote NuGet do seu projeto da seguinte forma:

"PackageID" : "version_constraint"

Por exemplo:

"dependencies": {
    "Microsoft.NETCore": "5.0.0",
    "System.Runtime.Serialization.Primitives": "4.0.10"
}

A seção dependencies é onde a caixa de diálogo Gerenciador de Pacotes NuGet adiciona dependências de pacote ao seu projeto.

A ID do pacote corresponde à id do pacote em nuget.org , a mesma que a id usada no console do gerenciador de pacotes: Install-Package Microsoft.NETCore.

Ao restaurar pacotes, a restrição de versão de "5.0.0" implica >= 5.0.0. Ou seja, se a 5.0.0 não estiver disponível no servidor, mas a 5.0.1 estiver, o NuGet instalará a 5.0.1 e avisará sobre a atualização. Caso contrário, o NuGet escolhe a versão mais baixa possível no servidor que corresponde à restrição.

Consulte de resolução de dependência para obter mais detalhes sobre as regras de resolução.

Gerenciando ativos de dependência

Quais ativos de dependências fluem para o projeto de nível superior é controlado especificando um conjunto delimitado por vírgulas de tags nas propriedades include e exclude da referência de dependência. As tags estão listadas na tabela abaixo:

As tags especificadas com exclude têm precedência sobre as especificadas com include. Por exemplo, include="runtime, compile" exclude="compile" é o mesmo que include="runtime".

Por exemplo, para incluir as pastas build e native de uma dependência, use o seguinte:

{
  "dependencies": {
    "packageA": {
      "version": "1.0.0",
      "include": "build, native"
    }
  }
}

Para excluir as pastas content e build de uma dependência, use o seguinte:

{
  "dependencies": {
    "packageA": {
      "version": "1.0.0",
      "exclude": "contentFiles, build"
    }
  }
}

Estruturas

Lista as estruturas nas quais o projeto é executado, como net45, netcoreapp, netstandard.

"frameworks": {
    "netcore50": {}
    }

Só é permitida uma única entrada na secção frameworks. (Uma exceção é project.json arquivos para projetos ASP.NET que são criados com a cadeia de ferramentas DNX obsoleta, que permite vários destinos.)

Tempos de execução

Lista os sistemas operacionais e arquiteturas em que seu aplicativo é executado, como win10-arm, win8-x64win8-x86.

"runtimes": {
    "win10-arm": { },
    "win10-arm-aot": { },
    "win10-x86": { },
    "win10-x86-aot": { },
    "win10-x64": { },
    "win10-x64-aot": { }
}

Um pacote contendo uma PCL que pode ser executada em qualquer tempo de execução não precisa especificar um tempo de execução. Isso também deve ser verdadeiro para quaisquer dependências, caso contrário, você deve especificar tempos de execução.

Apoios

Define um conjunto de verificações para dependências de pacote. Você pode definir onde espera que o PCL ou o aplicativo sejam executados. As definições não são restritivas, pois seu código pode ser executado em outro lugar. Mas especificar essas verificações faz com que o NuGet verifique se todas as dependências estão satisfeitas nos TxMs listados. Exemplos de valores para isso são: net46.app, uwp.10.0.app, etc.

Esta seção deve ser preenchida automaticamente quando você seleciona uma entrada na caixa de diálogo Destinos da Biblioteca de Classes Portátil.

"supports": {
    "net46.app": {},
    "uwp.10.0.app": {}
}

Importações

As importações são projetadas para permitir que pacotes que usam o dotnet TxM operem com pacotes que não declaram um TxM dotnet. Se o seu projeto estiver usando o dotnet TxM, todos os pacotes dos quais você depende também devem ter um dotnet TxM, a menos que você adicione o seguinte ao seu project.json para permitir que plataformas não dotnet sejam compatíveis com dotnet:

"frameworks": {
    "dotnet": { "imports" : "portable-net45+win81" }
}

Se você estiver usando o dotnet TxM, o sistema de projeto PCL adiciona a instrução imports apropriada com base nos destinos suportados.

Diferenças em relação a aplicativos portáteis e projetos da Web

O arquivo project.json usado pelo NuGet é um subconjunto do encontrado em ASP.NET projetos principais. No ASP.NET Core project.json é usado para metadados de projeto, informações de compilação e dependências. Quando usado em outros sistemas de projeto, essas três coisas são divididas em arquivos separados e project.json contém menos informações. Diferenças notáveis incluem:

• Só pode haver um quadro na secção frameworks.

• O arquivo não pode conter dependências, opções de compilação, etc. que você vê nos arquivos DNX project.json. Dado que só pode haver uma única estrutura, não faz sentido entrar em dependências específicas da estrutura.

• A compilação é tratada pelo MSBuild, portanto, as opções de compilação, as definições do pré-processador, etc. fazem parte do arquivo de projeto do MSBuild e não project.json.

No NuGet 3+, não se espera que os desenvolvedores editem manualmente o project.json, pois a interface do usuário do Gerenciador de Pacotes no Visual Studio manipula o conteúdo. Dito isso, você certamente pode editar o arquivo, mas você deve construir o projeto para iniciar uma restauração de pacote ou invocar a restauração de outra maneira. Consulte Restauração de pacotes.

project.lock.json

O arquivo project.lock.json é gerado no processo de restauração dos pacotes NuGet em projetos que usam project.json. Ele contém um instantâneo de todas as informações geradas à medida que o NuGet percorre o gráfico de pacotes e inclui a versão, o conteúdo e as dependências de todos os pacotes em seu projeto. O sistema de compilação usa isso para escolher pacotes de um local global que são relevantes ao criar o projeto, em vez de depender de uma pasta de pacotes locais no próprio projeto. Isso resulta em um desempenho de compilação mais rápido porque é necessário ler apenas project.lock.json em vez de muitos arquivos .nuspec separados.

project.lock.json é gerado automaticamente na restauração do pacote, portanto, pode ser omitido do controle do código-fonte adicionando-o aos arquivos .gitignore e .tfignore (consulte Pacotes e controle do código-fonte. No entanto, se você incluí-lo no controle do código-fonte, o histórico de alterações mostra as alterações nas dependências resolvidas ao longo do tempo.