Falha de Inicialização do IronPDF com WEBSITE_RUN_FROM_PACKAGE

Curtis Chau
Curtis Chau
Atualizado: 31 de agosto de 2026

IronPDF pode falhar na inicialização no Azure App Service e Azure Functions quando o aplicativo é implantado com WEBSITE_RUN_FROM_PACKAGE = 1. Essa configuração monta a raiz do aplicativo (C:\home\site\wwwroot) como um sistema de arquivos somente leitura, e a verificação do sistema de arquivos de inicialização do IronPDF falha contra ele, geralmente na primeira chamada do IronPDF, como a definição da chave de licença ou a conexão com um motor remoto.

System.IO.FileNotFoundException
Text

A verificação não é algo que o IronPDF exige intencionalmente. É um efeito colateral do carregamento automático da extensão padrão do Ninject. Como C:\home\site\wwwroot é somente leitura sob WEBSITE_RUN_FROM_PACKAGE = 1, a verificação lança FileNotFoundException e a inicialização para antes que qualquer trabalho de PDF seja executado.

Isso é corrigido no IronPDF 2026.8.1. Versões anteriores são afetadas, incluindo 2026.7.0.2, 2025.12.2, e 2025.3.6 no Windows (win-x64) sob .NET 10.

Solução

Qual passo você precisa depende de se você executa o IronPdfEngine remoto ou o IronPDF nativo.

IronPdfEngine Remoto e IronPdf.Slim

Atualize para o IronPDF 2026.8.1 ou posterior. A verificação de inicialização não mais gera erros, então WEBSITE_RUN_FROM_PACKAGE = 1 pode permanecer habilitado e nenhuma outra alteração é necessária. A renderização ocorre no motor, então nenhum binário nativo precisa ser extraído para a raiz do aplicativo somente leitura.

Veja Usar IronPDF com Modo no-Motor para configuração de conexão.

IronPDF Nativo

Atualizar sozinho não é suficiente aqui. Na inicialização, o IronPDF nativo extrai os binários do renderizador Chrome e as bibliotecas de tempo de execução para um local gravável, e um C:\home\site\wwwroot somente leitura bloqueia essa extração independentemente do bug de verificação acima.

Nas Configurações do Aplicativo do Azure, defina o seguinte e então reimplante:

WEBSITE_RUN_FROM_PACKAGE = 0
Text

Implantando a partir do Visual Studio? Desmarque Executar a partir do arquivo de pacote (recomendado) durante a etapa de Publicação.

Diálogo de Publicação do Visual Studio com a caixa de seleção Executar a partir do arquivo de pacote (recomendado) desmarcada

  • Dependendo do seu pipeline de implantação, essa configuração pode ser aplicada de vários locais diferentes. Descubra onde ela está definida e onde pode ser sobrescrita.
  • Para aplicar a alteração: você deve reimplantar. A configuração sozinha não tem efeito até que o aplicativo seja reimplantado.

Realocando os Caminhos Graváveis

A partir de 2026.8.1, quando o motor nativo não pode implantar seus binários Chromium e PDFium em um sistema de arquivos somente leitura, o erro de implantação nomeia a causa e os remédios disponíveis em vez de surgir uma falha ambígua a jusante. Um desses remédios é apontar os caminhos graváveis do IronPDF para fora da montagem do pacote:

IronPdf.Installation.TempFolderPath = @"D:\home\data\ironsoftware\";
IronPdf.Installation.CustomDeploymentDirectory = @"D:\home\data\ironsoftware\";

No Linux App Service, use /home/data/ironsoftware/ em vez disso. Defina isso antes da primeira chamada IronPDF. Se o renderizador ainda falhar ao implantar, defina WEBSITE_RUN_FROM_PACKAGE = 0 conforme descrito acima.

Se Você Não Pode Atualizar

Em versões antes de 2026.8.1, WEBSITE_RUN_FROM_PACKAGE = 0 é a única correção confiável tanto para o motor nativo quanto para o motor remoto, pois a verificação de inicialização ocorre antes de qualquer caminho de código ser alcançado.

Para mais contexto, veja o guia Azure Linux WEBSITE_RUN_FROM_PACKAGE.

Soluções Alternativas Que Não Funcionam nas Versões Afetadas

Todas foram tentadas contra versões antes de 2026.8.1, onde a verificação executa antes de tudo:

  • Mover a primeira chamada do IronPDF para fora da inicialização: a falha ainda acontece no primeiro uso de um endpoint sob demanda.
  • Alternar entre WEBSITE_RUN_FROM_ZIP e WEBSITE_RUN_FROM_PACKAGE: ambos montam como somente leitura e falham da mesma maneira.
  • Usar o remoto IronPdfEngine: a verificação de inicialização ainda executa primeiro, então falha antes da conexão remota ser usada. Este é o comportamento específico que 2026.8.1 corrige.
  • Definir Installation.TempFolderPath para um caminho gravável: a falha acontece antes que essa configuração seja lida. A partir de 2026.8.1 a configuração é lida normalmente.

Curtis Chau é bacharel em Ciência da Computação (Universidade Carleton) e se especializa em desenvolvimento front-end, com experiência em Node.js, TypeScript, JavaScript e React. Apaixonado por criar interfaces de usuário intuitivas e esteticamente agradáveis, Curtis gosta de trabalhar com frameworks modernos e criar manuais bem estruturados e visualmente atraentes.

Leia Mais

Pronto para começar?

Downloads no NuGet 22,198,312Versão:2026.11recém-lançado