Migração para v3.0.0

Há várias alterações de interrupção entre v2.20.0 e v3.0.0 que podem exigir alterações no nível de origem. Como lembrete, há dois tipos de alterações de interrupção:

1. Binário: quando um binário não pode mais ser usado como substituição de drop in
2. Fonte: quando a origem não é mais compilada

As alterações feitas no v3.0.0 foram uma remoção de obsoletões presentes no SDK por um tempo ou alterações necessárias por razões arquitetônicas (principalmente para melhor suporte a AOT e corte). A maioria dessas alterações deve estar no lado da alteração binária quebrando, ao mesmo tempo em que dá suporte à compilação e ao comportamento esperado com o código anterior. No entanto, há alguns chnages de quebra de origem a serem informados.

Alterações quebrando

O suporte ao .NET Standard 1.3 foi descartado

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

Ação necessária: se usar 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 declarado acima) permanecem as mesmas.

Ação necessária: Nenhuma

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

Estes 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 está agora no pacote DocumentFormat.OpenXml.Framework

Começando com v3.0.0, a estrutura de suporte para o SDK do Open XML agora está dentro de um pacote autônomo, DocumentFormat.OpenXml.Framework.

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

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

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

Observação

Esses tipos estão atualmente marcados como obsoletos, mas apenas no sentido de que nos reservamos o direito de alterar sua forma por feedback. Tenha cuidado ao usar esses tipos, pois eles podem mudar no futuro. Em algum momento, removeremos as obsoletões e elas serão consideradas APIs estáveis. Confira aqui para obter detalhes.

Ação necessária: se usar OpenXmlPackage.Package, o pacote retornado não será 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 dá suporte a , métodos de extensão podem ser gravados ISupportedRelationship<T>para dar suporte a comportamentos específicos que essa 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 é um struct readonly

Esse tipo costumava ter getters e setters mutáveis. Como struct, isso foi fácil de usar indevidamente, e deveria ter sido feito readonly desde o início.

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

EnumValue<TEnum> agora contém structs

Começando com v3.0.0, EnumValue<T> envolve 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 tipo C#, mas exigiam reflexão sobre o acesso, causando aplicativos compilados AOT muito grandes.

Ação necessária: a 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 em que foram (ou seja, valores de atributo).

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

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

Fica:

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> onde está disponível.

Ação necessária: como este é um struct, os padrões de código que podem ter um null resultado agora serão um OpenXmlElementList? em vez disso. As verificações nulas serão sinalizadas pelo compilador e o valor em si precisará ser desembrulhado, 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 readonly

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.

OpenXmlPartReader não sabe mais sobre todas as partes

Nas versões anteriores, o OpenXmlPartReader sabia sobre todas as partes fortemente tipada. Para reduzir o acoplamento necessário para melhores cenários de AOT, agora temos leitores digitados para pacotes conhecidos: WordprocessingDocumentPartReader, SpreadsheetDocumentPartReadere PresentationDocumentPartReader.

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

Atributos para informações de esquema foram removidos

SchemaAttrAttribute e ChildElementInfoAttribute foram removidos dos 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ê.

OpenXmlPackage.Close foi removido

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

Ação necessária: remover chamada e garantir que o pacote seja 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 repositório de backup.

Ação necessária: substitua o uso da propriedade estática pela instância.

OpenXmlPackage.PartExtensionProvider foi alterado

Essa propriedade forneceu um dicionário que permitia o acesso para alterar as extensões usadas. Isso agora é apoiado pelo IPartExtensionFeature.

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

Pacotes com MarkupCompatibilityProcessMode.ProcessAllParts agora realmente processam todas as partes

Anteriormente, havia uma heurística para potencialmente minimizar o processamento se nenhuma parte tivesse sido carregada. No entanto, isso causou cenários como os em que alguém editou manualmente o XML para não processar de fato ao salvar. v3.0.0 corrige esse comportamento e processa todas as partes se isso tiver sido optado.

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