Atualize para o .NET.NET Aspire 9.0

Artigo
12/15/2024

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

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

Dica

Se você é novo no .NET.NET Aspire, não há motivo para atualizar nada. Para obter mais informações, consulte a configuração e as ferramentas .NET.NET Aspire.

Pré-requisitos

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

Observação

Sinta-se à vontade para desinstalar a carga de trabalho .NET.NET Aspire, pois não precisará mais dela.

dotnet workload uninstall aspire

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

Se não desinstalares a carga de trabalho do .NET.NET Aspire e caso estejas a utilizar o novo SDK do .NET.NET Aspire e modelos do, verás tanto os modelos .NET Aspire 8.0 como .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. Os seguintes passos guiá-lo através do processo:

Edite o arquivo de projeto do host de aplicativo para utilizar 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 seu arquivo Program.cs para usar as novas APIs e remova todas as APIs obsoletas.

Editar o arquivo de projeto do host do aplicativo

Para atualizar seu projeto de host de aplicativo para o .NET.NET Aspire 9.0, você precisa atualizar seu arquivo de projeto para 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>

Opcionalmente, atualize o identificador da estrutura 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 os pacotes da versão 9.0, você ainda pode direcionar .NET 8.0. Se você quiser executar seu projeto .NET Aspire 9.0 no .NET 9.0, você precisa atualizar a propriedade TargetFramework em seu 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 do projeto de host 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 para a versão 9.0.0.

Ajustar o ficheiro Program.cs

Com a introdução do .NET.NET Aspire 9.0, há algumas mudanças . 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 de Program.cs na maioria dos casos.

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

Usar o Assistente de Atualização

O Upgrade Assistant é uma ferramenta que ajuda a atualizar projetos direcionados para a versão mais recente. Se você é novo no Assistente de Atualização, há duas modalidades para escolher:

A versão da extensão Visual Studio.
.NETda ferramenta global CLI .

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 o .NET Aspire 9.0 com Visual Studio, clique com o botão direito do mouse no projeto em 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 atualizações:

Com a opção Aspire atualizações selecionada, o Assistente de Atualização exibe os componentes de atualização alvo selecionáveis. Deixe todas as opções marcadas e selecione fazer upgrade da seleção:

Finalmente, depois de selecionar os componentes a serem atualizados, o Assistente de Atualização exibe os resultados do processo de atualização. Se tudo tiver sido bem-sucedido, verás sinais de verificação verdes ao lado de cada componente.

Para atualizar o projeto de host do aplicativo .NET.NET Aspire, certifique-se de ter instalado 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 Aspire atualizações. O Assistente de Atualização solicita a confirmação final. Digite 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):

Finalmente, após a conclusão do processo de atualização, o Assistente de Atualização exibe 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 .NET.NET Aspire, atualize todos os pacotes NuGet para a versão 9.0.0.

Para atualizar seu projeto de host de aplicativo, use o seguinte comando .NET CLI 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 para a versão especificada. Para obter mais informações, consulte 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

Como em qualquer atualização, certifique-se de que o aplicativo seja 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 era um problema antes. Se você encontrar algum problema, informe-nos preenchendo um problema de GitHub.

Partilhar via