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 de compatibilidade do 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 do .NET ou .NET em que seu aplicação é executado.

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

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

   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.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 de 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 pacote, que implementa o legado v1.x 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 , configure a propriedade EnableClientSideProjections de um objeto TranslationOptions para 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).

  • 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.

  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 Amazon Web Services Amazon Web Servicesa autenticação do MongoDB.Driver.Authentication.AWS Amazon Web Services ( Amazon Web Services ), adicione o pacote ao seu projeto e registre o provedor de autenticação no código de inicialização do aplicativo. Para saber mais sobre como usar a Amazon Web Services autenticação do .NETC# Amazon Web Services com o driver .NET /C#, consulte MONGODB-Amazon Web Services Amazon Web Services.

• 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 Infinity flutuante NaN e, 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 individuais do cluster de MongoClient.Cluster. Para escutar eventos de cluster, use ClusterBuilder.Subscribe().