Compartilhar via

Atualize para a versão .NET.NET Aspire 9.0

  • Artigo

.NET .NET Aspire 9.0 agora está disponível em geral. Neste artigo, você aprenderá as etapas envolvidas na atualização de seus projetos existentes .NET Aspire 8.x para .NET Aspire 9.0. Há algumas maneiras pelas quais você pode atualizar seus projetos para .NET.NET Aspire 9.0:

  • Atualize manualmente seus projetos para .NET.NET Aspire 9.0.
  • Use o do Assistente de Atualização para atualizar seus projetos para 9.0.

Dica

Se você não estiver familiarizado com .NET.NET Aspire, não haverá motivo para atualizar nada. Para obter mais informações, consulte .NET.NET Aspire configuração e ferramentas.

Pré-requisitos

Antes de atualizar seus projetos para .NET.NET Aspire 9.0, verifique se você tem os seguintes pré-requisitos:

Nota

Fique à vontade para desinstalar a carga de trabalho .NET.NET Aspire, pois você não precisará mais dela.

dotnet workload uninstall aspire

Para obter mais informações, consulte dotnet workload uninstall.

Se você não desinstalar a carga de trabalho .NET.NET Aspire e estiver usando o novo SDK .NET.NET Aspire e os modelos, você verá ambos os modelos .NET Aspire 8.0 e .NET Aspire 9.0.

Atualizar manualmente para o .NET.NET Aspire 9.0

Para atualizar seus projetos para o .NET.NET Aspire 9.0, você precisa atualizar seus arquivos de projeto. As etapas a seguir orientam você durante o processo:

  • Edite o arquivo de projeto do host do aplicativo para usar o novo SDK 9.0 do .NET.NET Aspire (Aspire.AppHost.Sdk).
  • Atualize os pacotes NuGet em seus arquivos de projeto para as versões mais recentes.
  • Ajuste o arquivo Program.cs para usar as novas APIs e remover as APIs obsoletas.

Editar o arquivo de projeto do host do aplicativo

Para atualizar o projeto de host do aplicativo para .NET.NET Aspire 9.0, você precisa atualizar o arquivo de projeto para passar a usar o novo 📦Aspire.AppHost.Sdk:

<Project Sdk="Microsoft.NET.Sdk">

+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="8.0.0" />
  </ItemGroup>

</Project>

Caso deseje, atualize o nome do framework de destino (TFM)

.NET Aspire 9.0 é executado no .NET 9.0, mas você também pode executá-lo no .NET 8.0. Em outras palavras, só porque você está usando o SDK do .NET Aspire e apontando para pacotes da versão 9.0, ainda é possível almejar o .NET 8.0. Se você quiser executar seu projeto .NET Aspire 9.0 no .NET 9.0, será necessário atualizar a propriedade TargetFramework no arquivo de projeto:

<Project Sdk="Microsoft.NET.Sdk">

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net8.0</TargetFramework>
+   <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>

</Project>

Para obter mais informações sobre TFMs, consulte Estruturas de destino em projetos no estilo SDK: versões mais recentes.

Diferenças gerais no projeto do anfitrião do aplicativo

Se você seguiu todas as etapas anteriores, o arquivo de projeto do host do aplicativo deverá ter esta aparência:

<Project Sdk="Microsoft.NET.Sdk">

+  <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net8.0</TargetFramework>
+   <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
-   <PackageReference Include="Aspire.Hosting.AppHost" Version="8.0.0" />
+   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>

</Project>

As alterações incluem a adição do Aspire.AppHost.Sdk, a atualização da propriedade TargetFramework para net9.0e a atualização do pacote Aspire.Hosting.AppHost à versão 9.0.0.

Ajustar seu arquivo de Program.cs

Com a introdução do .NET.NET Aspire 9.0, há algumas mudanças significativas. Algumas APIs foram originalmente marcadas como experimentais (com o ExperimentalAttribute) e agora são removidas, enquanto outras APIs agora são atribuídas como ObsoleteAttribute com detalhes sobre novas APIs de substituição. Você precisa ajustar seu arquivo de Program.cs (e potencialmente outras APIs afetadas) para usar as novas APIs. Se você estiver usando o Assistente de Atualização para atualizar seus projetos, ele ajustará automaticamente seu arquivo Program.cs na maioria dos casos.

Para obter a lista completa de alterações de ruptura no .NET.NET Aspire 9.0, consulte Alterações de ruptura no .NET.NET Aspire 9.0.

Usar o Assistente de Atualização

O Assistente de Atualização é uma ferramenta que ajuda a atualizar projetos direcionados para a versão mais recente. Se você não estiver familiarizado com o Assistente de Atualização, há duas modalidades para escolher:

Independentemente de como você instala o Assistente de Atualização, você pode usá-lo para atualizar seus projetos .NET Aspire 8.x para .NET Aspire 9.0.

Para atualizar o projeto de host do aplicativo .NET Aspire para .NET Aspire 9.0 com Visual Studio, clique com o botão direito do mouse no projeto no Gerenciador de Soluções e selecione Atualizar.

Importante

Se o Assistente de Atualização ainda não estiver instalado, você será solicitado a instalá-lo.

O Assistente de Atualização exibe um pacote de boas-vindas. Selecione a opção Aspire de atualizações:

Visual Studio: página de boas-vindas do Upgrade Assistant com o projeto de host do aplicativo .NET Aspire.

Com a opção de atualizações Aspire selecionada, o Assistente de Atualização mostra os alvos de atualização selecionáveis. Deixe todas as opções marcadas e selecione Atualizar seleção:

Visual Studio: Assistente de Upgrade .NET Aspire componentes selecionáveis para atualização.

Por fim, depois de selecionar os componentes a serem atualizados, o Assistente de Atualização exibirá os resultados do processo de atualização. Se tudo der certo, você verá marcas verdes ao lado de cada componente.

Visual Studio: Projeto de host do aplicativo .NET Aspire atualizado com sucesso pelo Assistente de Atualização.

Para atualizar o projeto de host do aplicativo .NET.NET Aspire, verifique se você instalou a CLI do Assistente de Atualização. Abra uma sessão de terminal no diretório raiz do arquivo de projeto do host do aplicativo .NET.NET Aspire e execute o seguinte comando:

upgrade-assistant upgrade

A saída é interativa, esperando que você selecione o tipo de atualização. Escolha a opção de atualizações Aspire:

 Selected options
────────────────────────────────────────────────────────────────────────────────────
 Source project     ..\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj

 Steps
────────────────────────────────
 Source project / Upgrade type
────────────────────────────────

How do you want to upgrade project AspireSample.AppHost?

> Aspire upgrades
    Upgrade to latest .NET Aspire version (aspire.latest)

  Upgrade project to a newer .NET version
    In-place project upgrade (framework.inplace)

  NuGet upgrades
    NuGet central package management (CPM) (nuget.cpm)

  Navigation
    Back
    Exit

Use o teclado para navegar para cima ↑ ou para baixo ↓, e selecione a opção de upgrades Aspire. O Assistente de Atualização solicita a confirmação final. Insira Y para continuar com a atualização:

 Selected options
────────────────────────────────────────────────────────────────────────────────────
 Source project     ..\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj
 Upgrade type       aspire.latest

 Steps
──────────────────────────────────────────
 Source project / Upgrade type / Upgrade
──────────────────────────────────────────

We have gathered all required options and are ready to do the upgrade. Do you want to continue? [y/n] (y):

Por fim, após a conclusão do processo de atualização, o Assistente de Atualização exibirá os resultados do processo de atualização:

Finalizing operation...
Complete: 3 succeeded, 0 failed, 7 skipped.

Atualizar os pacotes NuGet

Para aproveitar as atualizações mais recentes em sua solução de .NET.NET Aspire, atualize todos os pacotes NuGet para a versão 9.0.0.

Visual Studio: atualize todos os pacotes NuGet para a solução .NET Aspire.

Para atualizar o projeto de host do aplicativo, use o seguinte comando da CLI .NET para atualizar o pacote Aspire.Hosting.AppHost para a versão 9.0.0:

dotnet add package Aspire.Hosting.AppHost --version 9.0.0

Quando já existe uma referência de pacote, o comando dotnet add package atualiza a referência à versão especificada. Para obter mais informações, consulte o comando dotnet add package.

Com o projeto de host do aplicativo atualizado, seu arquivo de projeto deve ter esta aparência:

<Project Sdk="Microsoft.NET.Sdk">

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.0.0" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
-   <PackageReference Include="Aspire.Hosting.AppHost" Version="8.0.0" />
+   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>

</Project>

Dica

Você também desejará atualizar os pacotes NuGet em seus outros projetos para as versões mais recentes.

Verificar a atualização

Assim como acontece com qualquer atualização, verifique se o aplicativo é executado conforme o esperado e que todos os testes sejam aprovados. Crie a solução e procure sugestões, avisos ou erros na janela de saída— resolva qualquer coisa que não fosse um problema antes. Se você encontrar problemas, informe-nos arquivando um problema GitHub.