Migração para v3.0.0

Existem várias alterações interruptivas entre v2.20.0 e v3.0.0 que podem exigir alterações ao nível da origem. Como lembrete, existem dois tipos de alterações interruptivas:

1. Binário: quando um binário já não pode ser utilizado como queda na substituição
2. Origem: quando a origem já não é compilada

As alterações efetuadas na v3.0.0 foram uma remoção das obsoleções presentes no SDK durante algum tempo ou as alterações necessárias por razões de arquitetura (nomeadamente para um melhor suporte e limitação do AOT). A maioria destas alterações deve estar no lado da alteração interruptiva binária , ao mesmo tempo que suporta a compilação e o comportamento esperado com o código anterior. No entanto, existem alguns chnages de quebra de origem a ter em conta.

Alterações Interruptivas

O suporte do .NET Standard 1.3 foi removido

Nenhum destino ainda em suporte requer o .NET Standard 1.3 e pode utilizar o .NET Standard 2.0. O projeto ainda suporta .NET Framework 3.5+ e qualquer plataforma suportada pelo .NET Standard 2.0.

Ação necessária: se utilizar o .NET Standard 1.3, atualize para uma versão suportada do .NET

As arquiteturas 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 utilizadores, uma vez que as plataformas suportadas globalmente (além do .NET Standard 1.3 indicado acima) permanecem iguais.

Ação necessária: Nenhuma

OpenXmlPart/OpenXmlContainer/OpenXmlPackage já não tem construtores públicos

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

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

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

A partir da v3.0.0, a arquitetura de suporte para o SDK Open XML está agora dentro de um pacote autónomo, DocumentFormat.OpenXml.Framework.

Ação necessária: se quiser operar apenas OpenXmlPackage em tipos, já não precisa de introduzir todas as classes estáticas e pode apenas referenciar a biblioteca de arquitetura.

System.IO.Packaging já não é utilizado diretamente

Tem havido problemas com o comportamento de que precisamos no espaço de nomes System.IO.Packaging. A partir da v3.0, será utilizado um novo conjunto de interfaces no DocumentFormat.OpenXml.Packaging espaço de nomes para aceder às propriedades do pacote.

Observação

Estes tipos estão atualmente marcados como obsoletos, mas apenas no sentido em que reservamos o direito de alterar a forma por feedback. Tenha cuidado ao utilizar estes tipos, uma vez que podem mudar no futuro. Em algum momento, removeremos as obsoleções e serão consideradas APIs estáveis. Veja aqui para obter detalhes.

Ação necessária: se estiver a utilizar OpenXmlPackage.Package, o pacote devolvido já não é do tipo System.IO.Packaging.Package, mas sim de DocumentFormat.OpenXml.Packaging.IPackage.

Os métodos em partes para adicionar peças subordinadas são agora métodos de extensão

Havia uma série de métodos duplicados que adicionavam partes de formas bem definidas. Para consolidar esta situação, se uma parte suportar ISupportedRelationship<T>, os métodos de extensão podem ser escritos para suportar comportamentos específicos que uma parte pode fornecer. Os métodos existentes devem ser reenviados 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 só de leitura

Este tipo costumava ter getters e setters mutáveis. Como estrutura, isto foi fácil de usar indevidamente, e deveria ter sido só de leitura desde o início.

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

EnumValue<TEnum> contém agora estruturas

A partir da v3.0.0, EnumValue<T> molda um tipo personalizado que contém as informações sobre o valor de enumeração. Anteriormente, estes tipos eram armazenados em valores de enumeração no sistema de tipo C#, mas eram necessários reflexos para aceder, o que causava aplicações compiladas AOT muito grandes.

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

Uma alteração comum que é necessária são as instruções switch já não funcionarem:

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

torna-se:

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

OpenXmlElementList é agora uma estrutura

OpenXmlElementList é agora uma estrutura. Continua a implementar IEnumerable<OpenXmlElement> para além do IReadOnlyList<OpenXmlElement> local onde está disponível.

Ação necessária: uma vez que se trata de uma estrutura, os padrões de código que podem ter um null resultado serão agora um OpenXmlElementList? . As verificações nulas serão sinalizadas pelo compilador e o valor em si terá de 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 uma estrutura só de leitura

Este tipo é utilizado para enumerar pares numa parte e causou muitas alocações desnecessárias. Esta alteração deve ser transparente após a recompilação.

Ação necessária: uma vez que se trata agora de uma estrutura, o código de processamento nulo terá de ser atualizado.

O OpenXmlPartReader já não conhece todas as partes

Em versões anteriores, OpenXmlPartReader sabia de todas as partes com um tipo de letra forte. Para reduzir o acoplamento necessário para melhores cenários de AOT, escrevemos leitores para pacotes conhecidos: WordprocessingDocumentPartReader, SpreadsheetDocumentPartReadere PresentationDocumentPartReader.

Ação necessária: substitua a utilização de por leitores específicos do OpenXmlPartReader documento, se necessário. Se criar um leitor de peças a partir de um pacote conhecido, utilize os construtores que utilizam um existente OpenXmlPart que, em seguida, criará as partes com tipos de letra esperados.

Os atributos das informações de esquema foram removidos

SchemaAttrAttribute e ChildElementInfoAttribute foram removidos dos tipos e os próprios tipos já não estão presentes.

Ação necessária: se estes tipos forem necessários, contacte-nos no GitHub para identificar o melhor caminho a seguir.

OpenXmlPackage.Close foi removido

Isto não fez nada de útil além da chamada .Dispose(), mas causou confusão sobre o que deveria ser chamado. Isto é agora removido com a expectativa de chamar .Dispose(), de preferência com o padrão de utilização.

Ação necessária: Remova a chamada e certifique-se de que o pacote está eliminado corretamente

OpenXmlPackage.CanSave é agora uma propriedade de instância

Esta propriedade costumava ser uma propriedade estática dependente da arquitetura. Agora, pode mudar por instância de pacote, dependendo das definições e do arquivo de cópia de segurança.

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

OpenXmlPackage.PartExtensionProvider foi alterado

Esta propriedade forneceu um dicionário que permitia o acesso para alterar as extensões utilizadas. Esta ação é agora apoiada pelo IPartExtensionFeature.

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

Os pacotes com MarkupCompatibilityProcessMode.ProcessAllParts processam agora todas as partes

Anteriormente, havia uma heurística para minimizar potencialmente o processamento se não tivessem sido carregadas partes. No entanto, isto causou cenários como os em que alguém editou manualmente o XML para não processar realmente ao guardar. a v3.0.0 corrige este comportamento e processa toda a parte se esta opção tiver sido ativada.

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