SDK v3 para .NET de Azure Cosmos DB para la API para NoSQL: descarga y notas de la versión

Links
Notas de la versión Notas de la versión
Descarga del SDK NuGet
Documentación de API Documentación de referencia de api de .NET
Muestras ejemplos de código de .NET
Comenzar Introducción al SDK de Azure Cosmos DB .NET
Procedimientos recomendados Procedimientos recomendados para Azure Cosmos DB .NET SDK
Tutorial de Entity Framework Core Entity Framework Core con proveedor de Azure Cosmos DB
Marco admitido actual Microsoft .NET Standard 2.0

Historial de lanzamientos

El historial de versiones se mantiene en el repositorio de origen del SDK de .NET de Azure Cosmos DB. Para obtener una lista detallada de versiones de actualización de características y errores corregidos en cada versión, vea la documentación del registro de cambios del SDK.

Para obtener la versión mínima recomendada Azure Cosmos DB .NET SDK, consulte la sección Versión recomendada del registro de cambios del SDK. Use la versión recomendada o posterior para incluir todas las correcciones críticas.

Problemas conocidos

Para obtener una lista de problemas conocidos con la versión mínima recomendada del SDK, consulte la sección Problemas conocidos del registro de cambios del SDK.

Administración de dependencias de Newtonsoft.Json

Overview

El SDK de .NET de Azure Cosmos DB tiene una dependencia de Newtonsoft.Json para las operaciones de serialización JSON. Esta dependencia no se administra automáticamente : debe agregar Newtonsoft.Json explícitamente como una dependencia directa en el proyecto.

El SDK se compila contra Newtonsoft.Json 10.x, que internamente tiene una vulnerabilidad de seguridad conocida. Aunque el SDK es técnicamente compatible con 10.x y el uso del SDK de Newtonsoft.Json no es susceptible al problema de seguridad notificado, se recomienda usar la versión 13.0.3 o superior para evitar posibles problemas de seguridad o conflictos. Las versiones 13.x incluyen cambios importantes, pero los patrones de uso del SDK son compatibles con estos cambios.

Importante

Esta dependencia es necesaria incluso cuando se usa System.Text.Json para tipos definidos por el usuario a través de CosmosClientOptions.UseSystemTextJsonSerializerWithOptions, ya que las operaciones internas del SDK siguen usando Newtonsoft.Json para los tipos de sistema.

Agregue siempre explícitamente Newtonsoft.Json la versión 13.0.3 o posterior como dependencia directa al usar el SDK v3 de Azure Cosmos DB .NET. No use la versión 10.x debido a vulnerabilidades de seguridad conocidas.

Para proyectos .csproj estándar

<ItemGroup>
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Para proyectos que usan la administración central de paquetes

Si el proyecto usa Directory.Packages.props:

<Project>
  <ItemGroup>
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Solución de problemas de conflictos de versiones

Falta la referencia a Newtonsoft.Json

Si se produce un error de compilación como:

The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2. Please add a reference to Newtonsoft.Json or set the 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Este error se genera intencionadamente mediante los destinos de compilación del SDK de Cosmos DB para asegurarse de que la dependencia está configurada correctamente.

Solución para aplicaciones:

Agregue una referencia explícita a Newtonsoft.Json como se muestra en la sección Configuración recomendada anterior.

Solución para bibliotecas:

Si estás desarrollando una biblioteca (no una aplicación) y deseas diferir la dependencia Newtonsoft.Json a los consumidores de tu biblioteca, puedes omitir esta comprobación estableciendo la propiedad MSBuild en .csproj:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

Warning

Solo use este desvío al compilar bibliotecas en las que los usuarios finales proporcionarán la dependencia Newtonsoft.Json. En el caso de las aplicaciones, agregue siempre la referencia explícita.

Conflictos de versión del paquete

Si se producen errores de compilación como:

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3

Solution:

  1. Identifique la versión necesaria comprobando qué paquetes necesitan versiones más recientes:

    dotnet list package --include-transitive | Select-String "Newtonsoft.Json"
    
  2. Actualice la versión del paquete centralizado para que coincida o supere la versión necesaria más alta:

    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
    
  3. Limpiar y recompilar:

    dotnet clean
    dotnet restore
    dotnet build
    

Compatibilidad de versiones

En la tabla siguiente se muestran las versiones seguras mínimas recomendadas de Newtonsoft.Json para cada versión del SDK de Cosmos DB. Aunque el SDK puede funcionar técnicamente con 10.x, estas versiones nunca se deben usar debido a vulnerabilidades de seguridad.

Versión del SDK de Cosmos DB Versión segura mínima Recomendado
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Tip

Al usar .NET Aspire 13.0.0 o posterior, asegúrese de que Newtonsoft.Json está en la versión 13.0.4 para evitar conflictos con los componentes de Azure de Aspire.

Procedimientos recomendados

  • Agregar siempre como dependencia directa : el SDK no administra automáticamente esta dependencia.
  • Use la versión 13.0.3 o posterior : nunca use 10.x a pesar de la compatibilidad técnica, debido a vulnerabilidades de seguridad conocidas.
  • Obligatorio incluso con System.Text.Json : debe incluir Newtonsoft.Json incluso cuando se usa UseSystemTextJsonSerializerWithOptions, ya que el SDK lo usa internamente para los tipos de sistema.
  • Anclar la versión explícitamente : no confiar en la resolución de dependencias transitiva
  • Supervisión de advertencias : tratar las advertencias de degradación del paquete NuGet (NU1109) como errores en las canalizaciones de CI/CD

FAQ

¿Cómo recibiré una notificación del SDK de retirada?

Microsoft proporciona un aviso anticipado de 12 meses antes del final del soporte técnico del SDK de retirada para ayudarle a realizar la transición sin problemas a un SDK compatible. Recibirá notificaciones a través de estos canales de comunicación: el portal de Azure, las actualizaciones Azure y la comunicación directa a los administradores de servicios asignados.

¿Puedo crear aplicaciones mediante un SDK de Azure Cosmos DB retirado to-bedurante el período de 12 meses?

Sí, puede usar el SDK de to-beretirado Azure Cosmos DB para crear, implementar y modificar aplicaciones durante el período de aviso de 12 meses. Se recomienda migrar a una versión compatible más reciente del SDK de Azure Cosmos DB durante el período de aviso de 12 meses, según corresponda.

Después de la fecha de retirada, ¿qué ocurre con las aplicaciones que usan el SDK de Azure Cosmos DB no admitido?

Después de la fecha de retirada, Azure Cosmos DB ya no realiza correcciones de errores, agrega nuevas características o proporciona compatibilidad con las versiones retiradas del SDK. Si decide no actualizar, Azure Cosmos DB sigue sirviendo solicitudes enviadas desde las versiones retiradas del SDK.

¿Qué versiones del SDK tendrán las características y actualizaciones más recientes?

Las nuevas características y actualizaciones solo se agregan a la versión secundaria más reciente de la versión principal compatible más reciente del SDK. Se recomienda que use siempre la versión más reciente para aprovechar las ventajas de las nuevas características, mejoras de rendimiento y correcciones de errores. Si usa una versión antigua y no retirada del SDK, las solicitudes para Azure Cosmos DB siguen funcionando, pero no tiene acceso a ninguna funcionalidad nueva.

¿Qué debo hacer si no puedo actualizar mi aplicación antes de una fecha límite?

Se recomienda que actualice al SDK más reciente tan pronto como sea posible. Después de etiquetar un SDK para la retirada, tiene 12 meses para actualizar la aplicación. Si no puede actualizar por la fecha de retirada, Azure Cosmos DB sigue recibiendo solicitudes enviadas desde las versiones retiradas del SDK, por lo que las aplicaciones en ejecución continúan funcionando. Pero Azure Cosmos DB ya no realiza correcciones de errores, agrega nuevas características o proporciona compatibilidad con las versiones retiradas del SDK.

Si tiene un plan de soporte técnico y requiere soporte técnico, póngase en contacto con nosotros al abrir una incidencia de soporte técnico.

¿Cómo puedo solicitar características que se agreguen a un SDK o conector?

Las nuevas características no siempre se agregan a todos los SDK o conectores inmediatamente. Si hay una característica que no se admite que le gustaría agregar, agregue comentarios a nuestro foro de la comunidad.