Atualize para a versão 3.0

Visão geral

Esta página descreve as alterações que você pode precisar fazer no seu aplicação ao atualizar o driver .NET/C# para a versão 3.0.

Como fazer a atualização

Esta página lista as possíveis alterações introduzidas pelo .NET/C# Driver versão 3.0. Para atualizar o driver .NET/C# para a versão 3.0, siga estas etapas:

1. Revise a página Compatibilidade para garantir que a nova versão do driver seja compatível com as versões do MongoDB Server às quais seu aplicação se conecta e com a versão da estrutura .NET ou .NET em que seu aplicação é executado.

2. Se você estiver usando uma versão 2.x do driver .NET/C#, atualize para v2.30. Para fazer isso, siga o guia de atualização do v2.x.

3. Resolva as alterações significativas descritas na seção Alterações 3.0 significativas da versão.

   Exemplo

   Se você estiver atualizando o driver da v2.14 para a v3.0, primeiro use a v2.x guia de atualização para atualizar seu driver para v2.30. Em seguida, resolva todas as alterações de quebra para v3.0.

Versão 3.5 Alterações interruptivas

• O driver elimina o suporte para o MongoDB Server 4.0 e versões anteriores. Você deve atualizar seu MongoDB Server para v4.2 ou posterior.

  Para saber como atualizar seu MongoDB Server, consulte Notas da versão no manual do MongoDB Server.

  Para saber mais sobre a compatibilidade entre as versões do driver .NET/C# e as versões do MongoDB Server, visite a página Compatibilidade.

Versão 3.0 Alterações interruptivas

• O driver elimina o suporte para o MongoDB Server v3.6 e versões anteriores. Você deve atualizar seu MongoDB Server para v4.0 ou posterior.

  Para saber como atualizar seu MongoDB Server, consulte Notas da versão no manual do MongoDB Server.

  Para saber mais sobre a compatibilidade entre as versões do driver .NET/C# e as versões do MongoDB Server, visite a página Compatibilidade.

• O driver elimina o suporte para .NET Core 2.x e .NET Framework 4.6. Você deve atualizar para o .NET Core 3.x ou posterior ou .NET Framework 4.7.2 ou posterior.

  Para saber mais sobre a compatibilidade entre as versões do driver .NET/C# e as versões .NET, visite a página Compatibilidade.

• O driver remove o pacote mongocsharpdriver NuGet, que implementa o v1.x legado API nas versões do driver 2.x. Se você estiver usando o v1.x API, você deverá migrar para a nova API.

• As classes, métodos e propriedades no namespace MongoDB.Driver.Core que foram preteridos em v2.30 estão marcados como internal. Se o driver fornecer uma substituição para uma classe, método ou propriedade2.30 obsoleta, as mensagens do compilador na v a exibirão.

• Os métodos, propriedades e construtores no namespace MongoDB.Bson que foram preteridos em versões anteriores do driver foram removidos. Se o driver fornecer uma substituição para um método, propriedade ou construtor obsoleto, as mensagens do compilador na v2.30 o exibirão.

• O driver elimina o suporte para o mecanismo de autenticação MONGODB-CR. Para saber mais sobre como configurar a autenticação no driver .NET/C#, consulte Mecanismos de autenticação.

• O driver substitui a interface IMongoQueryable pela interface IQueryable, seguindo o padrão usado pela maioria dos outros provedores LINQ. Se seu aplicação contiver referências a IMongoQueryable, substitua-as por IQueryable.

• O driver remove o método ClusterBuilder.ConfigureSdamLogging(). Para configurar o registro em seu aplicação, consulte o Guia de Registro.

• O fornecedor LINQ2 foi removido desta versão do driver. Você deve usar LINQ3 para todas as queries LINQ.

  As queries que usam projeções do lado do cliente gerarão um erro ExpressionNotSupportedException por padrão. Para habilitar projeções do lado do cliente , defina a propriedade EnableClientSideProjections de um objeto TranslationOptions como true. Você pode passar esse objeto TranslationOptions para um objeto AggregateOptions ou FindOptions para habilitar as projeções do lado do cliente para uma única query ou para um objeto MongoClientSettings para habilitar as projeções do lado do cliente para todas as queries em um aplicação.

• As versões anteriores do driver .NET/C# suportavam dois modos de representação de GUID. Na versão 3.0, GuidRepresentationMode.V3 é o único modo suportado. Esta alteração tem os seguintes efeitos no condutor:

  • O construtor BsonBinaryData(Guid) foi removido. Para construir um objeto BsonBinaryData a partir de um GUID, use o construtor BsonBinaryData.Create(Guid, GuidRepresentation). Para visualizar um exemplo de criação de um GUID legado, consulte a nota Construir GUIDs Legados no guia Serialização de GUID.

  • A propriedade BsonBinaryData.GuidRepresentation foi removida.

  • Você pode chamar o método BsonBinaryData.ToGuid() somente em objetos BsonBinaryData do subtipo 4. Se o objeto tiver qualquer outro subtipo, você deverá chamar o método BsonBinaryData.ToGuid(GuidRepresentation) e especificar o subtipo.

  • A conversão de GUID usando a classe BsonTypeMapper foi removida. Para converter valores GUID em BSON, use o construtor BsonBinaryData(<GUID>, GuidRepresentation.Standard).

  As alterações anteriores afetam seu aplicação somente se você serializar e desserializar documentos BSON diretamente. Se você mapear seus documentos MongoDB somente para POCOs, o GuidRepresentationMode não afetará seu aplicação.

  Para saber mais sobre a serialização de GUIDs no driver .NET/C#, consulte a página de GUIDs.

• As classes de exceção e seus tipos relacionados não contêm mais o atributo [Serializable] e, portanto, não suportam mais a API de serialização legado da Microsoft. Para saber como usar o driver .NET/C# para serializar objetos, consulte o guia Serialização.

• TLS 1.0 e 1.1 não são mais compatíveis. Você deve usar TLS 1.2 ou superior. Para saber mais sobre como configurar TLS/SSL no .NET/C# Driver, consulte Habilitar TLS em uma conexão.

• Por padrão, o driver serializa os valores Decimal128 e decimal como valores BSON Decimal128. Nas versões anteriores do driver, o driver serializava esses valores como valores BSON string por padrão. Para serializar um valor decimal ou Decimal128 como uma string na v3.0, aplique o atributo [BsonRepresentation(BsonType.String)] ao campo .

  Para saber mais sobre como especificar tipos de BSON types BSON durante a serialização, consulte a seção Serialização personalizada da página POCOs.

• Por padrão, o driver serializa DateTimeOffset valores como documentos BSON. Nas versões anteriores do driver, o driver serializava esses valores como arrays BSON por padrão. Para serializar um valor DateTimeOffset como uma array na v3.0, aplique o atributo [BsonRepresentation(BsonType.Array)] ao campo.

• O modo de saída JSON padrão é JSON estendido relaxado, um formato de string baseado no padrão JSON que descreve documentos BSON. O JSON estendido relaxado enfatiza a legibilidade e a interoperabilidade às custas da preservação do tipo.

  Para usar um modo de saída JSON diferente, crie um novo objeto JsonWriterSettings. Defina a propriedade OutputMode deste objeto como um valor do enumeração JsonOutputMode e, em seguida, passe o objeto para o método ToJson() ao serializar o documento. O seguinte exemplo de código mostra como serializar um documento BSON para Strict JSON:

  // Configure JsonWriterSettings
  var jsonWriterSettings = new JsonWriterSettings
  {
      OutputMode = JsonOutputMode.Strict
  };
  // Serialize the document to JSON using the configured settings
  var json = document.ToJson(jsonWriterSettings);

• O construtor MongoClient aceita apenas um objeto Credential em vez de um array.

• Para usar a autenticação do Amazon Web Services (Amazon Web Services), você deve adicionar o pacote MongoDB.Driver.Authentication.AWS ao seu projeto e registrar o provedor de autenticação no código de inicialização do aplicativo. Para saber mais sobre como usar a autenticação do Amazon Web Services com o driver .NET/C#, consulte Autenticação do Amazon Web Services IAM.

• Para usar a criptografia em execução, você deve adicionar o pacote MongoDB.Driver.Encryption ao seu projeto e registrar o mecanismo de criptografia no código de inicialização do aplicativo. Para saber mais sobre como usar a criptografia em execução em execução com o driver .NET/C#, consulte criptografia em execução em execução no manual do MongoDB Server .

• Se você tentar serializar ou desserializar um valor de ponto flutuante Infinity ou NaN para uma representação integral, o driver lançará um OverflowException. Para saber mais sobre os valores de ponto flutuante Infinity e NaN, consulte double.NaN, double.PositiveInfinity e double.NegativeInfinity. no MSDN.

• O driver inclui as seguintes alterações na classe BsonValue :

  • Remove o atributo [Obsolete] das propriedades AsLocalTime e AsUniversalTime.

  • Adiciona as propriedades AsNullableLocalTime e AsNullableUniversalTime.

  • Remove a propriedade AsDateTime. Em vez disso, use a propriedade AsUniversalTime.

  • Remove a propriedade AsNullableDateTime. Em vez disso, use a propriedade AsNullableUniversalTime.

• O driver remove eventos de cluster individuais de MongoClient.Cluster. Para escutar eventos de cluster, ligue para o método ClusterBuilder.Subscribe().

• Se qualquer tipo em uma collection usar um discriminador escalar, o driver lançará uma exceção se você executar uma das seguintes ações na collection:

  • Chame o método Aggregate().OfType<T>(), como no exemplo a seguir:

    collection.Aggregate().OfType<T>()

  • Chame o método Aggregate().Match(item => item is T), como no exemplo a seguir:

    collection.Aggregate().Match(item => item is T)

  Para usar qualquer um dos métodos anteriores em uma coleção, você pode aplicar um discriminador hierárquico a cada classe na coleção. Consulte a página Objetos polimórficos para saber como.

  Alternativamente, você pode verificar o tipo de cada item de uma maneira diferente. Por exemplo, você pode chamar o método Where() e passar uma expressão que compara o tipo do item com o tipo que você está procurando, como no exemplo a seguir:

  collection.AsQueryable().Where(item => item.GetType() == typeof(T));

  Para saber mais sobre discriminadores de tipo, consulte Objetos polimórficos.

• O driver selou alguns tipos que não foram projetados para extensão usando herança. Isso inclui as seguintes alterações:

  • O driver sela todos os serializadores de concreto. Para implementar um serializador personalizado, implemente a interface IBsonSerializer .

  • O driver marca as classes MongoClient, MongoDatabase e MongoCollection. Recomendamos usar as interfaces IMongoClient, IMongoDatabase e IMongoCollection diretamente.

• O driver exige que os aplicativos configurem explicitamente como serializar GUIDs usando as classes GuidSerializer e ObjectSerializer. Os usuários do driver .NET/C# que criam novos aplicativos podem implementar um GuidSerializer global registrando-o. Recomendamos que os usuários com aplicativos mais antigos verifiquem se todos os GUIDs são serializados da mesma maneira ao implementar um GuidSerializer global. Você também pode configurar a serialização GUID caso a caso sem registrar um GuidSerializer global.

  Para saber mais sobre a serialização de GUID, consulte o guia de GUIDs.

• Por padrão, o driver serializa valores TimeOnly como valores BSON int64 representando Ticks. Versões anteriores do driver serializaram valores TimeOnly como documentos BSON por padrão.

  Para serializar um valor TimeOnly como um documento na v3.0 ou posterior, registre um TimeOnlySerializer com representação BsonType.Document, conforme mostrado no exemplo a seguir:

  BsonSerializer.RegisterSerializer(new TimeOnlySerializer(BsonType.Document));

  Você também pode aplicar o atributo BsonRepresentation(BsonType.Document) a campos TimeOnly, conforme mostrado no exemplo a seguir:

  public class Person
  {
      [BsonRepresentation(BsonType.Document)]
      public TimeOnly TimeBirth {get; set;}
  }