Cursos
Módulo
En este módulo, aprenderá cuándo, por qué y cómo modernizar una aplicación de ASP.NET Framework a ASP.NET Core utilizando el Asistente para actualización.
Este explorador ya no se admite.
Actualice a Microsoft Edge para aprovechar las características y actualizaciones de seguridad más recientes, y disponer de soporte técnico.
Cuando se dirige a un marco en una aplicación o biblioteca, debe especificar el conjunto de API que quiere poner a disposición de la aplicación o biblioteca. La plataforma de destino se especifica en el archivo del proyecto mediante un moniker de la plataforma de destino (TFM).
Una aplicación o biblioteca puede tener como destino una versión de .NET Standard. Las versiones de .NET Standard representan conjuntos estandarizados de API en todas las implementaciones de .NET. Por ejemplo, una biblioteca puede tener como destino .NET Standard 1.6 y obtener acceso a las API que funcionan en .NET Core y .NET Framework con el mismo código base.
Una aplicación o biblioteca también puede tener como destino una implementación específica de .NET para obtener acceso a las API específicas de la implementación. Por ejemplo, una aplicación que tenga como destino Xamarin.iOS (por ejemplo, Xamarin.iOS10
) tiene acceso a contenedores de API de iOS proporcionados por Xamarin para iOS 10, o una aplicación que tenga como destino la Plataforma universal de Windows (UWP, uap10.0
) tiene acceso a las API que compilan para dispositivos que ejecutan Windows 10.
Para algunas plataformas de destino (por ejemplo, .NET Framework), las API se definen mediante los ensamblados que la plataforma instala en un sistema y pueden incluir API del marco de trabajo de la aplicación (por ejemplo, ASP.NET).
Para plataformas de destino basadas en paquetes (por ejemplo, .NET 5+, .NET Standard y .NET Core), las API se definen mediante los paquetes NuGet incluidos en la aplicación o biblioteca.
En la tabla siguiente se definen las plataformas de destino más comunes, cómo se hace referencia a ellas y la versión de .NET Standard que implementan. Estas versiones de plataformas de destino son las últimas versiones estables. No se muestran las versiones preliminares. Un moniker de la plataforma de destino (TFM) es un formato de token normalizado para especificar la plataforma de destino de una aplicación o biblioteca de .NET.
Marco de destino | Más reciente versión estable |
Moniker de la plataforma de destino (TFM) | Implementado versión de .NET Standard |
---|---|---|---|
.NET 9 | 9 | net9.0 | 2.1 |
.NET 8 | 8 | net8.0 | 2.1 |
.NET Standard | 2.1 | netstandard2.1 | N/D |
.NET Core | 3.1 | netcoreapp3.1 | 2.1 |
.NET Framework | 4.8.1 | net481 | 2.0 |
Normalmente, un TFM hace referencia a una plataforma de destino. En la tabla siguiente, se muestran las plataformas de destino compatibles con el SDK de .NET y el cliente de NuGet. Los equivalentes se muestran entre corchetes. Por ejemplo, win81
es un TFM equivalente a netcore451
.
Versión de .NET Framework de destino | TFM |
---|---|
.NET 5+ (y .NET Core) | netcoreapp1.0 netcoreapp1.1 netcoreapp2.0 netcoreapp2.1 netcoreapp2.2 netcoreapp3.0 netcoreapp3.1 net5.0* net6.0* net7.0* net8.0* |
.NET Standard | netstandard1.0 netstandard1.1 netstandard1.2 netstandard1.3 netstandard1.4 netstandard1.5 netstandard1.6 netstandard2.0 netstandard2.1 |
.NET Framework | net11 net20 net35 net40 net403 net45 net451 net452 net46 net461 net462 net47 net471 net472 net48 net481 |
Tienda Windows | netcore [netcore45] netcore45 [win] [win8] netcore451 [win81] |
.NET Micro Framework | netmf |
Silverlight | sl4 sl5 |
Windows Phone | wp [wp7] wp7 wp75 wp8 wp81 wpa81 |
Plataforma universal de Windows | uap [uap10.0] uap10.0 [win10] [netcore50] |
* Los TFM de .NET 5 y versiones posteriores incluyen variaciones específicas del sistema operativo. Para obtener más información, vea la sección siguiente TFM específicos del sistema operativo de .NET 5+.
Los net5.0
TMM , net6.0
, net7.0
, net8.0
y net.0
incluyen tecnologías que funcionan en distintas plataformas. La especificación de un TFM específico del sistema operativo hace que las API concretas de un sistema operativo estén disponibles para la aplicación, por ejemplo, Windows Forms o enlaces de iOS. Los TFM específicos del sistema operativo también heredan todas las API disponibles para el TFM base, por ejemplo, el TFM net9.0
.
En .NET 5 se ha presentado el TFM específico del sistema operativo net5.0-windows
, que incluye enlaces específicos de Windows para las API de WinForms, WPF y UWP. .NET 6 y versiones posteriores tienen TFM adicionales específicos del sistema operativo, por ejemplo, net6.0-ios
.
En la tabla siguiente se muestra la compatibilidad de los TFM de .NET 5.
TFM | Compatible con |
---|---|
net5.0 |
net1.4 (con la advertencia NU1701) netcoreapp1.3.1 (advertencia cuando se hace referencia a WinForms o WPF) netstandard1.2.1 |
net5.0-windows |
netcoreapp1.3.1 (más todo lo demás heredado de net5.0 ) |
net6.0 |
(versión posterior de net5.0 ) |
net6.0-android |
xamarin.android (más todo lo demás heredado de net6.0 ) |
net6.0-ios |
Todo heredado de net6.0 |
net6.0-maccatalyst |
Todo heredado de net6.0 |
net6.0-macos |
Todo heredado de net6.0 |
net6.0-tvos |
Todo heredado de net6.0 |
net6.0-windows |
(versión posterior de net5.0-windows ) |
net7.0 |
(versión posterior de net6.0 ) |
net7.0-android |
(versión posterior de net6.0-android ) |
net7.0-ios |
(versión posterior de net6.0-ios ) |
net7.0-maccatalyst |
(versión posterior de net6.0-maccatalyst ) |
net7.0-macos |
(versión posterior de net6.0-macos ) |
net7.0-tizen |
tizen40 (más todo lo demás heredado de net7.0 ) |
net7.0-tvos |
(versión posterior de net6.0-tvos ) |
net7.0-windows |
(versión posterior de net6.0-windows ) |
net8.0 |
(versión posterior de net7.0 ) |
net8.0-android |
(versión posterior de net7.0-android ) |
net8.0-browser |
Todo heredado de net8.0 |
net8.0-ios |
(versión posterior de net7.0-ios ) |
net8.0-maccatalyst |
(versión posterior de net7.0-maccatalyst ) |
net8.0-macos |
(versión posterior de net7.0-macos ) |
net8.0-tizen |
(versión posterior de net7.0-tizen ) |
net8.0-tvos |
(versión posterior de net7.0-tvos ) |
net8.0-windows |
(versión posterior de net7.0-windows ) |
net9.0 |
(versión posterior de net8.0 ) |
net9.0-android |
(versión posterior de net8.0-android ) |
net9.0-browser |
(versión posterior de net8.0-browser ) |
net9.0-ios |
(versión posterior de net8.0-ios ) |
net9.0-maccatalyst |
(versión posterior de net8.0-maccatalyst ) |
net9.0-macos |
(versión posterior de net8.0-macos ) |
net9.0-tizen |
(versión posterior de net8.0-tizen ) |
net9.0-tvos |
(versión posterior de net8.0-tvos ) |
net9.0-windows |
(versión posterior de net8.0-windows ) |
Para que la aplicación sea portable entre distintas plataformas pero todavía tenga acceso a API específicas del sistema operativo, puede seleccionar como destino varios TFM específicos del sistema operativo y agregar restricciones de plataforma alrededor de llamadas API específicas del sistema operativo mediante directivas de preprocesador #if
. Para obtener una lista de los símbolos disponibles, consulte Símbolos de preprocesador.
Siga estas instrucciones para determinar qué TFM usar en la aplicación:
net9.0
. Esto incluye la mayoría de las bibliotecas, pero también ASP.NET Core y Entity Framework.net9.0-windows
.net9.0
), pero también otros tipos específicos de la plataforma para obtener más API o características.También puede especificar una versión opcional del sistema operativo al final del TFM específico del sistema operativo, por ejemplo, net6.0-ios15.0
. La versión indica cuáles son las API que están disponibles para la aplicación o la biblioteca. No controla la versión del sistema operativo que admite la aplicación o la biblioteca en tiempo de ejecución. Se usa para seleccionar los ensamblados de referencia en los que se compila el proyecto, y para seleccionar recursos de paquetes NuGet. Considere esta versión como la "versión de la plataforma" o la "versión de la API del sistema operativo" para distinguirla de la versión del sistema operativo en tiempo de ejecución.
Cuando un TFM específico del sistema operativo no especifica explícitamente la versión de la plataforma, tiene un valor implícito que puede deducirse del TFM base y del nombre de la plataforma. Por ejemplo, el valor de plataforma predeterminado para iOS en .NET 6 es 31.0
, lo que significa que net6.0-android
es una abreviatura del TFM net6.0-android31.0
canónico. La versión implícita de la plataforma para un TFM base más reciente puede ser mayor, por ejemplo, un TFM net8.0-android
futuro podría asignarse a net8.0-android34.0
. El formulario abreviado está pensado para su uso solo en archivos de proyecto y se expande al formato canónico mediante los destinos MSBuild del SDK de .NET antes de pasarse a otras herramientas, como NuGet.
En la tabla siguiente se muestran los valores predeterminados de la plataforma de destino (TPV) para cada versión de .NET.
Versión de .NET | Android | iOS | Mac Catalyst | macOS | tvOS | Tizen | Windows |
---|---|---|---|---|---|---|---|
.NET 8 | 34,0 | 17.2 | 17.2 | 14,2 | 17.1 | 7.0 | 10.0 |
.NET 9 | 35,0 | 18.0 | 18.0 | 15.0 | 7.0 | 10.0 |
Nota
En las plataformas de Apple (iOS, macOS, tvOS y Mac Catalyst) en .NET 8 y versiones anteriores, el TPV predeterminado es la última versión admitida en la carga de trabajo instalada actualmente. Esto significa que la actualización de la carga de trabajo de iOS en .NET 8, por ejemplo, puede dar lugar a un TPV predeterminado más alto, si se ha añadido compatibilidad con una nueva versión de iOS en esa carga de trabajo. En la tabla anterior, el TPV por defecto es el de la versión inicial para la versión de .NET indicada.
A partir de .NET 9, este comportamiento especial solo se aplica a los proyectos ejecutables. Ahora, el TPV predeterminado para los proyectos de bibliotecas sigue siendo el mismo durante toda una versión principal de .NET, al igual que para el resto de plataformas.
El SDK de .NET está diseñado para poder admitir las API recién publicadas para una plataforma individual sin una nueva versión del TFM base. Esto le permite acceder a la funcionalidad específica de la plataforma sin esperar a una versión principal de .NET. Puede obtener acceso a estas API recién publicadas incrementando la versión de la plataforma en el TFM. Por ejemplo, si la plataforma Android añadía API de nivel 32 en una actualización del SDK de .NET 6.0.x, se podía acceder a ellas mediante el TFM net6.0-android32.0
.
Si la aplicación hace referencia a un paquete que tiene varios recursos para diferentes TFM, se prefieren los recursos que están más cerca del número de versión. Por ejemplo, si la aplicación tiene como destino net6.0-ios
y el paquete ofrece recursos para net6.0
y net5.0-ios
, se usan los recursos de net6.0
. Para más información, vea Precedencias.
Aunque una aplicación o una biblioteca específicas de la plataforma se compilan en las API de una versión específica de ese sistema operativo, puede hacerlas compatibles con versiones anteriores del sistema operativo agregando la propiedad SupportedOSPlatformVersion
al archivo del proyecto. La propiedad SupportedOSPlatformVersion
indica la versión mínima del sistema operativo necesaria para ejecutar la aplicación o la biblioteca. Si no especifica explícitamente esta versión mínima del sistema operativo en tiempo de ejecución en el proyecto, se toma como valor predeterminado la versión de la plataforma del TFM.
Para que la aplicación se ejecute correctamente en una versión anterior del sistema operativo, no puede llamar a las API que no existen en esa versión del sistema operativo. Sin embargo, puede agregar medidas de protección en torno a las llamadas a las API más recientes para que solo se llamen cuando se ejecuten en una versión del sistema operativo que las admita. Este patrón le permite diseñar la aplicación o la biblioteca para que admitan la ejecución en versiones anteriores del sistema operativo, al tiempo que se aprovechan las ventajas de la funcionalidad más reciente del sistema operativo cuando se ejecuta en versiones más recientes de este.
El valor SupportedOSPlatformVersion
(ya sea explícito o predeterminado) lo usa el analizador de compatibilidad de la plataforma, que detecta y advierte sobre las llamadas sin protección a API más recientes. Se graba en el ensamblado compilado del proyecto como un atributo de ensamblado UnsupportedOSPlatformAttribute, de modo que el analizador de compatibilidad de la plataforma pueda detectar llamadas sin protección a las API de ese ensamblado desde proyectos con un valor SupportedOSPlatformVersion
inferior. En algunas plataformas, el valor SupportedOSPlatformVersion
afecta a los procesos de compilación y empaquetado de aplicaciones específicos de la plataforma, que se tratan en la documentación de esas plataformas.
Este es un extracto de ejemplo de un archivo de proyecto que usa las propiedades TargetFramework
y SupportedOSPlatformVersion
de MSBuild para especificar que la aplicación o la biblioteca tienen acceso a las API de iOS 15.0, pero admite la ejecución en iOS 13.0 y posteriores:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net6.0-ios15.0</TargetFramework>
<SupportedOSPlatformVersion>13.0</SupportedOSPlatformVersion>
</PropertyGroup>
...
</Project>
Las plataformas de destino se especifican en un archivo del proyecto. Cuando especifique una única plataforma de destino, use el elemento TargetFramework. El siguiente archivo de proyecto de aplicación de consola muestra cómo dirigirse a .NET 9:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<OutputType>Exe</OutputType>
<TargetFramework>net9.0</TargetFramework>
</PropertyGroup>
</Project>
Al especificar varias plataformas de destino, puede hacer referencia de forma condicional a ensamblados para cada plataforma de destino. En el código, puede compilar de forma condicional en esos ensamblados utilizando símbolos de preprocesador con lógica if-then-else.
El siguiente proyecto de biblioteca tiene como destino las API de .NET Standard (netstandard1.4
) y de .NET Framework (net40
y net45
). Use el elemento TargetFrameworks plural con varias plataformas de destino. Los atributos Condition
incluyen paquetes específicos de la implementación cuando se compila la biblioteca para los dos TFM de .NET Framework:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>netstandard1.4;net40;net45</TargetFrameworks>
</PropertyGroup>
<!-- Conditionally obtain references for the .NET Framework 4.0 target -->
<ItemGroup Condition=" '$(TargetFramework)' == 'net40' ">
<Reference Include="System.Net" />
</ItemGroup>
<!-- Conditionally obtain references for the .NET Framework 4.5 target -->
<ItemGroup Condition=" '$(TargetFramework)' == 'net45' ">
<Reference Include="System.Net.Http" />
<Reference Include="System.Threading.Tasks" />
</ItemGroup>
</Project>
Dentro de su aplicación o biblioteca, puede escribir código condicional mediante directivas de preprocesador para compilar para cada plataforma de destino:
public class MyClass
{
static void Main()
{
#if NET40
Console.WriteLine("Target framework: .NET Framework 4.0");
#elif NET45
Console.WriteLine("Target framework: .NET Framework 4.5");
#else
Console.WriteLine("Target framework: .NET Standard 1.4");
#endif
}
}
El sistema de compilación es consciente de los símbolos de preprocesador que representan las plataformas de destino que se muestran en la tabla Versiones compatibles de las plataformas de destino cuando se usan proyectos de estilo SDK. Para convertir un TFM de .NET Standard, .NET Core o .NET 5+ a un símbolo de preprocesador, reemplace los puntos y guiones por un carácter de subrayado y cambie las letras minúsculas por mayúsculas (por ejemplo, el símbolo de netstandard1.4
es NETSTANDARD1_4
).
Puede deshabilitar la generación de estos símbolos mediante la propiedad DisableImplicitFrameworkDefines
. Para más información acerca de esta propiedad, consulte DisableImplicitFrameworkDefines.
La lista completa de símbolos de preprocesador para plataformas de destino de .NET es la siguiente:
Versiones de .NET Framework de destino | Símbolos | Símbolos adicionales (disponible en SDK de .NET 5+) |
Símbolos de plataforma (solo disponibles cuando se especifica un TFM específico del sistema operativo) |
---|---|---|---|
.NET Framework | NETFRAMEWORK , NET481 , NET48 , NET472 , , NET47 NET471 , NET462 , NET461 , NET35 NET40 NET46 NET452 NET451 NET45 NET20 |
NET48_OR_GREATER , NET472_OR_GREATER , NET471_OR_GREATER , NET47_OR_GREATER , , NET461_OR_GREATER NET462_OR_GREATER , NET46_OR_GREATER , NET452_OR_GREATER NET451_OR_GREATER NET45_OR_GREATER NET40_OR_GREATER NET35_OR_GREATER NET20_OR_GREATER |
|
.NET Standard | NETSTANDARD , NETSTANDARD2_1 , NETSTANDARD2_0 , NETSTANDARD1_6 , NETSTANDARD1_5 , NETSTANDARD1_4 , NETSTANDARD1_3 , NETSTANDARD1_2 , , NETSTANDARD1_1 NETSTANDARD1_0 |
NETSTANDARD2_1_OR_GREATER , NETSTANDARD2_0_OR_GREATER , NETSTANDARD1_6_OR_GREATER , NETSTANDARD1_5_OR_GREATER , NETSTANDARD1_4_OR_GREATER , NETSTANDARD1_3_OR_GREATER , NETSTANDARD1_2_OR_GREATER , , NETSTANDARD1_1_OR_GREATER NETSTANDARD1_0_OR_GREATER |
|
.NET 5+ (y .NET Core) | NET , NET9_0 , NET8_0 , NET7_0 , , NET5_0 NET6_0 , NETCOREAPP , NETCOREAPP3_1 NETCOREAPP3_0 NETCOREAPP2_1 NETCOREAPP2_2 , , NETCOREAPP1_1 NETCOREAPP2_0 NETCOREAPP1_0 |
NET8_0_OR_GREATER , NET7_0_OR_GREATER , NET6_0_OR_GREATER , NET5_0_OR_GREATER , NETCOREAPP3_1_OR_GREATER , NETCOREAPP3_0_OR_GREATER , NETCOREAPP2_2_OR_GREATER , NETCOREAPP2_1_OR_GREATER , NETCOREAPP2_0_OR_GREATER , , NETCOREAPP1_1_OR_GREATER NETCOREAPP1_0_OR_GREATER |
ANDROID , BROWSER , IOS , MACCATALYST , MACOS , TVOS , , WINDOWS [OS][version] (por ejemplo IOS15_1 ),[OS][version]_OR_GREATER (por ejemplo, IOS15_1_OR_GREATER ) |
Nota
<framework>_OR_GREATER
se definen para la versión de destino y todas las versiones anteriores. Por ejemplo, si tiene como destino .NET Framework 2.0, se definen los símbolos siguientes: NET20
, NET20_OR_GREATER
, NET11_OR_GREATER
y NET10_OR_GREATER
.NETSTANDARD<x>_<y>_OR_GREATER
solo se definen para destinos de .NET Standard y no para destinos que implementan .NET Standard, como .NET Core y .NET Framework.TargetFramework
y NuGet.Las siguientes plataformas de destino están en desuso. Los paquetes que tienen como destino estas plataformas deben migrarse a los reemplazos indicados.
TFM en desuso | Replacement |
---|---|
aspnet50 aspnetcore50 dnxcore50 dnx dnx45 dnx451 dnx452 |
netcoreapp |
dotnet dotnet50 dotnet51 dotnet52 dotnet53 dotnet54 dotnet55 dotnet56 |
netstandard |
netcore50 | uap10.0 |
win | netcore45 |
win8 | netcore45 |
win81 | netcore451 |
win10 | uap10.0 |
winrt | netcore45 |
Comentarios de .NET
.NET es un proyecto de código abierto. Seleccione un vínculo para proporcionar comentarios:
Cursos
Módulo
En este módulo, aprenderá cuándo, por qué y cómo modernizar una aplicación de ASP.NET Framework a ASP.NET Core utilizando el Asistente para actualización.