Migração para v3.0.0

Há uma série de alterações significativas entre a v2.20.0 e a v3.0.0 que podem exigir alterações no nível da origem. Como lembrete, há dois tipos de alterações significativas:

1. Binário: quando um binário não pode mais ser usado como substituição
2. Origem: quando a fonte não compila mais

As alterações feitas na v3.0.0 foram uma remoção de obsoletos presentes no SDK por um tempo ou alterações necessárias por razões arquitetônicas (principalmente para melhor suporte e corte AOT). A maioria dessas alterações deve estar no lado da alteração de quebra binária , enquanto ainda dá suporte à compilação e ao comportamento esperado com seu código anterior. No entanto, existem algumas fontes de quebra de fontes a serem cientes.

Alterações interruptivas

O suporte ao .NET Standard 1.3 foi descartado

Nenhum destino ainda em suporte exige o .NET Standard 1.3 e pode usar o .NET Standard 2.0. O projeto ainda dá suporte ao .NET Framework 3.5+ e a qualquer plataforma compatível com o .NET Standard 2.0.

Ação necessária: se estiver usando o .NET Standard 1.3, atualize para uma versão com suporte do .NET

As estruturas de destino foram alteradas

Para simplificar a criação de pacotes, os TFMs criados foram alterados para alguns dos pacotes. No entanto, não deve haver nenhuma alteração aparente para os usuários, pois as plataformas com suporte geral (além do .NET Standard 1.3 mencionado acima) permanecem as mesmas.

Ação necessária: nenhuma

OpenXmlPart/OpenXmlContainer/OpenXmlPackage não têm mais construtores públicos

Eles nunca inicializaram o comportamento correto e nunca deveriam ter sido expostos.

Ação necessária: use .Create(...) métodos em vez de construtor.

A estrutura de suporte para tipos OpenXML agora está no pacote DocumentFormat.OpenXml.Framework

A partir da v3.0.0, a estrutura de suporte para o SDK do Open XML agora está dentro de um pacote independente, DocumentFormat.OpenXml.Framework.

Ação necessária: se você quiser operar apenas OpenXmlPackage em tipos, não precisará mais trazer todas as classes estáticas e poderá apenas fazer referência à biblioteca de estruturas.

System.IO.Packaging não é mais usado diretamente

Houve problemas com a obtenção do comportamento de que precisamos do namespace System.IO.Packaging. A partir da v3.0, um novo conjunto de interfaces no namespace será usado para acessar as DocumentFormat.OpenXml.Packaging propriedades do pacote.

Ação necessária: Se estiver usando OpenXmlPackage.Package, o pacote retornado não é mais do tipo System.IO.Packaging.Package, mas de DocumentFormat.OpenXml.Packaging.IPackage.

Métodos em partes para adicionar partes filho agora são métodos de extensão

Havia uma série de métodos duplicados que adicionariam partes de maneiras bem definidas. Para consolidar isso, se uma parte suporta ISupportedRelationship<T>, métodos de extensão podem ser escritos para suportar o comportamento específico que a parte pode fornecer. Os métodos existentes para isso devem ser redirecionados de forma transparente para os novos métodos de extensão após a compilação.

Ação necessária: nenhuma

OpenXmlAttribute agora é uma estrutura somente leitura

Esse tipo costumava ter getters e setters mutáveis. Como estrutura, isso era fácil de usar indevidamente e deveria ter sido feito somente leitura desde o início.

Ação necessária: se espera alterar um OpenXmlAttribute no local, crie um novo.

EnumValue<TEnum> agora contém structs

A partir da v3.0.0, EnumValue<T> encapsula um tipo personalizado que contém as informações sobre o valor de enumeração. Anteriormente, esses tipos eram armazenados em valores de enumeração no sistema de tipos C#, mas exigiam reflexão para acessar, causando aplicativos compilados AOT muito grandes.

Ação necessária: uma superfície de API semelhante está disponível, no entanto, os valores de enumeração expostos para isso não são mais constantes e não estarão disponíveis em alguns cenários que eram (ou seja, valores de atributo).

Uma alteração comum necessária é que as instruções switch não funcionam mais:

switch (theCell.DataType.Value)
{
  case CellValues.SharedString:
    // Handle the case
    break;
}

torna-se:

if (theCell.DataType.Value == CellValues.SharedString)
{
  // Handle the case
}

OpenXmlElementList agora é um struct

OpenXmlElementList agora é um struct. Ele ainda implementa IEnumerable<OpenXmlElement> além de IReadOnlyList<OpenXmlElement> quando disponível.

Ação necessária: como esta é uma estrutura, os padrões de código que podem ter um null resultado agora serão um OpenXmlElementList? . As verificações nulas serão sinalizadas pelo compilador e o próprio valor precisará ser desencapsulado, como:

- OpenXmlElementList? slideIds = part?.Presentation?.SlideIdList?.ChildElements;
+ OpenXmlElementList slideIds = part?.Presentation?.SlideIdList?.ChildElements ?? default;

ou

- OpenXmlElementList? slideIds = part?.Presentation?.SlideIdList?.ChildElements;
+ OpenXmlElementList slideIds = (part?.Presentation?.SlideIdList?.ChildElements).GetValueOrDefault();

IdPartPair agora é um struct somente leitura

Esse tipo é usado para enumerar pares em uma parte e causou muitas alocações desnecessárias. Essa alteração deve ser transparente após a recompilação.

Ação necessária: como agora é um struct, o código de tratamento nulo precisará ser atualizado.

O OpenXmlPartReader não conhece mais todas as partes

Nas versões anteriores, OpenXmlPartReader conhecia sobre todas as partes fortemente tipadas. Para reduzir o acoplamento necessário para melhores cenários AOT, agora temos leitores de tipos para pacotes conhecidos: WordprocessingDocumentPartReader, SpreadsheetDocumentPartReader, e PresentationDocumentPartReader.

Ação necessária: Substitua o uso de por leitores específicos do OpenXmlPartReader documento, se necessário. Se estiver criando um leitor de peças a partir de um pacote conhecido, use os construtores que usam um existente OpenXmlPart , o que criará as partes fortemente tipadas esperadas.

Os atributos para informações de esquema foram removidos

SchemaAttrAttribute e ChildElementInfoAttribute foram removidos de tipos e os próprios tipos não estão mais presentes.

Ação necessária: se esses tipos forem necessários, entre em contato conosco no GitHub para identificar o melhor caminho a seguir para você.

O OpenXmlPackage.Close foi removido

Isso não fez nada de útil além de chamar .Dispose(), mas causou confusão sobre qual deveria ser chamado. Isso agora é removido com a expectativa de chamar .Dispose(), de preferência com o padrão using.

Ação necessária: remova a chamada e certifique-se de que o pacote esteja descartado corretamente

OpenXmlPackage.CanSave agora é uma propriedade de instância

Essa propriedade costumava ser uma propriedade estática que dependia da estrutura. Agora, ele pode alterar a instância por pacote, dependendo das configurações e do armazenamento de backup.

Ação necessária: substitua o uso da propriedade static por instance.

O OpenXmlPackage.PartExtensionProvider foi alterado

Esta propriedade forneceu um dicionário que permitiu o acesso para alterar as extensões usadas. Agora é apoiado pelo IPartExtensionFeature.

Ação necessária: Substitua o uso por OpenXmlPackage.Features.GetRequired<IPartExtensionFeature>().

Os pacotes com MarkupCompatibilityProcessMode.ProcessAllParts agora processam todas as partes

Anteriormente, havia uma heurística para potencialmente minimizar o processamento se nenhuma parte tivesse sido carregada. No entanto, isso fez com que cenários como aqueles em que alguém editou manualmente o XML não processassem realmente ao salvar. A v3.0.0 corrige esse comportamento e processa todas as partes se isso tiver sido aceito.

Ação necessária: Se você deseja que apenas peças carregadas sejam processadas, altere para MarkupCompatibilityProcessMode.ProcessLoadedPartsOnly