Plugin Conversor
Converta documentos para 45 formatos de destino
O plugin Conversor transforma o Doconut em um serviço de conversão de documentos. Ele fornece o mecanismo por trás da fachada pública DocumentConverter e — opcionalmente — um widget pronto servido por DocImage.axd, permitindo que você converta documentos a partir de C#, do widget ou de um frontend que você mesmo escreva.
| Superfície | Quando usar |
|---|---|
DocumentConverter (C#) | Você converte no servidor, sem navegador envolvido |
Widget incorporável (doconutConverter.js) | Você quer uma tela pronta de upload, conversão e download em sua página |
Endpoints HTTP em DocImage.axd (?convert=open|run|download) | Você constrói sua própria UI de conversão contra um contrato de servidor documentado |
Instalar o pacote
Install-Package Doconut.NETFramework.ConverterPara fixar o plugin na versão que esta documentação descreve:
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Mantenha o pacote Conversor na mesma versão que Doconut.NETFramework.
O arquivo de licença do plugin, Doconut.Viewer.Converter.lic, vai na mesma pasta que Doconut.Viewer.lic; ele é lido junto com a licença do visualizador.
Registrar o plugin
Todo plugin registra da mesma forma: AddPlugin<TPlugin>() em DoconutHost.Initialize, chamado de Application_Start.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});Isso é tudo que a fachada C# precisa. O widget e seus endpoints HTTP são um opt-in separado, AddConverterWidget() (veja Widget incorporável).
O plugin precisa de uma licença que conceda a capacidade Converter. Sem ela, DoconutHost.Initialize lança uma exceção de Application_Start:
Exemplo de exceção lançada quando a licença está ausente:
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.Em System.Web isso significa que cada requisição responde com um 500 vazio, e o motivo está apenas no log de eventos do Windows (fonte ASP.NET). Ele lança para falta de licença, um arquivo legado TRIAL, uma licença sem Converter, e uma licença paga usada fora da sua janela de versão. Licenças temporárias Demo/NFR são aceitas. Veja Configuração de Licença.
Licenciamento & marca d'água
| Estado da licença | Inicialização | Saída da conversão |
|---|---|---|
Licença de visualizador paga concedendo Converter, dentro da sua janela de versão | Inicia | Limpo — watermarked: false |
| Licença Temporária Ativa (Demo/NFR) | Inicia | Converte, com a marca d'água de avaliação — watermarked: true |
| Licença Temporária Expirada (Demo/NFR) | Inicia | Converte, com a marca d'água de avaliação — watermarked: true |
Sem licença, um arquivo legado TRIAL, uma licença sem Converter, ou uma licença paga fora da sua janela de versão | Application_Start lança; cada requisição responde um 500 vazio | — |
A fachada DocumentConverter e o manipulador ?convert=run do widget aplicam a mesma regra. Uma integração pode ser construída e testada de ponta a ponta com uma licença de avaliação antes da compra — apenas os bytes de saída mudam.
Uma fonte DICOM (.dcm, .ima) também precisa da capacidade Dicom. Sem ela, ConvertAsync lança um LicenseException (Converting '.dcm' requires the Dicom capability license.) e o open do widget responde 403.
Uso a partir de C#
Cada conversão retorna um MemoryStream buscável posicionado em 0. DocumentConverter é sem estado: resolva‑lo a partir de DoconutHost.Services onde precisar e reutilize livremente.
// Resolva DocumentConverter de DoconutHost.Services; seu construtor é interno, portanto nunca `new` ele.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension inclui o ponto inicial. password é null a menos que o documento esteja protegido.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html: um Stream contendo o HTML para converter de volta em um documento Word, como o resultado de WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);Dois detalhes que são fáceis de errar: sourceExtension na sobrecarga de stream deve incluir o ponto inicial (".xlsx", não "xlsx"), caso contrário não resolve. E apesar do nome, WordToHtmlAsync retorna Task<Stream>, não Task<string> — o documento HTML (imagens incorporadas como Base64) chega como um stream, como todo outro resultado.
O chamador possui o MemoryStream que uma conversão retorna e deve descartá‑lo após copiar ou retorná‑lo (o File(stream, …) do MVC descarta‑lo para você). Não construa ou descarte DocumentConverter você mesmo — seu construtor é interno.
Em um controlador MVC 5
Torne a ação assíncrona e await a conversão:
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
Stream pdf = await converter.ConvertAsync(
file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
password: null, ct: Response.ClientDisconnectedToken);
return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}Em Web Forms: nunca bloqueie uma conversão
Uma página Web Forms é executada em um contexto de requisição de thread única. ConvertAsync retoma nesse contexto quando termina, portanto uma página que espera por ela de forma síncrona — .Result, .Wait(), .GetAwaiter().GetResult() — ocupa a própria thread que a conversão precisa para concluir. A requisição nunca retorna. O navegador continua girando, o IIS não registra nada, e o resto do site continua funcionando, parecendo uma conversão lenta em vez de um deadlock.
Marque a página Async="true" e execute a conversão como uma tarefa assíncrona da página:
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms: a diretiva @Page precisa de Async="true", e a conversão é executada como uma tarefa assíncrona da página.
// Bloquear nele em vez disso (.Result, .Wait(), .GetAwaiter().GetResult()) causa deadlock na requisição:
// ele nunca retorna, e nada é registrado.
protected void Page_Load(object sender, EventArgs e)
{
if (!IsPostBack) return;
RegisterAsyncTask(new PageAsyncTask(async ct =>
{
var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
using (var pdf = await converter.ConvertAsync(
Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
using (var ms = new MemoryStream())
{
if (pdf.CanSeek) pdf.Position = 0;
await pdf.CopyToAsync(ms);
Response.ContentType = "application/pdf";
Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
Response.BinaryWrite(ms.ToArray());
// Context, não HttpContext.Current: após um await o último pode ser nulo.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Sem Async="true" na diretiva @Page, RegisterAsyncTask é ignorado silenciosamente. Após um await, use o Context da página; HttpContext.Current pode ser null lá.
Formatos de destino
ConversionTarget (namespace Doconut.Configs.Conversion) tem 45 membros:
Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, IcoNem toda fonte converte para todo destino: cada família de formato de fonte (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, documento web, DICOM) tem seu próprio conjunto de destinos permitidos. Converter uma fonte DICOM (.dcm, .ima) também requer uma licença que conceda a capacidade Dicom; seus destinos são Pdf, Png, Jpeg, Bmp, Tiff e Gif. Não codifique esse enum como a lista de destinos da sua UI: ?convert=open retorna o allowedTargets para o arquivo enviado, e isso é o que deve alimentar um seletor.
Widget incorporável
Habilitar os endpoints
Os endpoints ?convert=open|run|download do widget são servidos por DocImage.axd e estão desativados por padrão. Habilite-os ao lado do registro do plugin:
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget(widget =>
{
widget.MaxUploadMb = 25;
});
});
// System.Web lê todo o upload antes que Doconut o veja: mantenha maxRequestLength (KB) e
// maxAllowedContentLength (bytes) no Web.config acima do MaxUploadMb do widget.AddConverterWidget() sem argumento habilita o widget com os padrões (MaxUploadMb = 25). Ele não concede direitos de conversão por si só: precisa de AddPlugin<ConverterPlugin>(), ou DoconutHost.Initialize lança:
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.Duas coisas a verificar quando o widget se comporta de forma inadequada:
basePath: '/DocImage.axd'. O padrão do widget,/doconut, é o endpoint ASP.NET Core. Neste pacote, os endpoints são o manipuladorDocImage.axddeWeb.config.- O script e os endpoints são independentes. O módulo de recursos serve
doconutConverter.jsindependentemente de o widget estar habilitado ou não. SemAddConverterWidget(), o widget carrega, pinta sua zona de arraste e parece totalmente correto — e sua primeira ação responde404.
Limites de upload
ASP.NET lê todo o corpo da requisição antes que DocImage.axd seja executado. Um upload acima de MaxUploadMb mas abaixo dos limites do host obtém o JSON próprio do widget 413 (File is too large.). Um upload acima dos limites do host é rejeitado primeiro pelo IIS, com uma página de erro que o widget não consegue ler. Mantenha ambos os limites do host em Web.config acima do limite do widget:
<system.web>
<httpRuntime maxRequestLength="30720" /> <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
<security>
<requestFiltering>
<requestLimits maxAllowedContentLength="31457280" /> <!-- BYTES: 30 MB -->
</requestFiltering>
</security>
</system.webServer>Incorpore-o
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd', maxUploadMb: 25 });
</script>Doconut.convert(selectorOrElement, options) aceita um seletor CSS ou um elemento, lança uma exceção se a montagem não for encontrada e retorna um manipulador. O widget envia um arquivo, mostra uma pré‑visualização da página 1, permite que o usuário escolha um dos allowedTargets, converte, pré‑visualiza o resultado quando possível e oferece o download.
Opções
| Opção | Tipo | Padrão | Observações |
|---|---|---|---|
basePath | string | /doconut | A URL do endpoint. Defina '/DocImage.axd' neste pacote |
resPath | string | /doconut-res | Aceito por consistência com outros widgets Doconut; o widget conversor não constrói nenhuma URL a partir dele |
maxUploadMb | number | 25 | Apenas pré‑verificação no cliente; o servidor impõe seu próprio limite |
licenseUrl | string | null | null | Transforma o aviso de marca d'água na tela de resultado em um link |
labels | object | {} | Substitui qualquer subconjunto das strings em inglês do widget |
Retornos de chamada
| Callback | Dispara quando | Carga |
|---|---|---|
onReady() | O widget renderizou sua tela de arraste | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open tem sucesso | Token de origem, contagem de páginas, extensão da origem (sem ponto inicial), destinos permitidos |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run tem sucesso | A resposta da execução mais o target solicitado |
onDownload({ downloadName, downloadToken }) | O usuário clica em Download | Dispara junto com o download próprio do navegador |
onError({ phase, message }) | Uma solicitação de abrir ou executar falha | phase é 'open' ou 'run'; message é o erro do servidor sanitizado |
Um callback que lança uma exceção é capturado e registrado; ele nunca interrompe o fluxo do widget.
Manipulador imperativo
Doconut.convert() retorna a instância do widget:
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // Um File do seu próprio <input type="file" id="picker">
conv.reset(); // volta à tela de drop; não dispara novamente onReady
conv.loadFile(file); // inicia o fluxo com um File; não faz nada a menos que o widget esteja na sua tela de drop
conv.destroy(); // remove listeners, esvazia o mount; a instância torna‑se inutilizável após issoRótulos
Cada string tem um padrão em inglês; labels substitui qualquer subconjunto e o restante permanece em inglês. Fragmentos que mudam em tempo de execução usam {placeholders}, como uploading: 'Uploading {name}…' e pages: '{n} pages'.
| Chave | Padrão em inglês |
|---|---|
dropPrompt | Drag & drop a document here |
dropHint | PDF, Word, Excel, PowerPoint, images and more |
chooseFile | Choose file |
uploading | Uploading {name}… |
page / pages | 1 page / {n} pages |
noTargets | No conversion targets are available for this file. |
convertTo / convert | Convert to / Convert |
converting | Converting to {target}… |
readyToDownload | Ready to download |
download / convertAnother | Download / Convert another |
watermarkNotice | Output is watermarked — get a license to remove it. |
retry | Retry |
genericError | Something went wrong. Please try again. |
sizeLimit | That file is larger than the {mb} MB upload limit. Please choose a smaller file. |
serverError | The server could not process this request. Please try again. |
networkError | Could not reach the server. Please check your connection and try again. |
Outras chaves cobrem o aria-label da zona de arraste (dropAriaLabel), os textos de pré‑visualização alt (previewAlt, resultAlt), a forma vinculada do aviso de marca d'água usado com licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), uma resposta ilegível (badResponse) e os anúncios aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
Um erro JSON do servidor é exibido como o servidor o escreveu; serverError é usado apenas quando uma resposta com falha não contém erro JSON, como o 404 de um widget desativado.
Tematização
O widget adiciona a classe dcw ao seu elemento de montagem e lê suas cores, raio e fonte a partir de propriedades CSS personalizadas, permitindo que você o tematize sem tocar em seus detalhes internos:
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}Padrões: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px e uma fonte de UI do sistema para --dcw-font.
Construa seu próprio frontend
O widget é um cliente para este contrato HTTP em DocImage.axd. As rotas respondem com 404 até que AddConverterWidget() seja chamado. Erros carregam um corpo JSON, { "error": "..." }, exceto onde a tabela indica “apenas status”. Um valor desconhecido de ?convert= responde com 400.
| Rota | Propósito | Resposta de sucesso |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, one file) | Carregar e abrir um documento fonte | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Converter o fonte carregado para target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Transmitir o arquivo convertido | 200 — o arquivo, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt na resposta open não tem ponto inicial ("docx") — o oposto do parâmetro sourceExtension de ConvertAsync. allowedTargets lista nomes de destino em minúsculas ("pdf", "html", …); passe um deles como target, que é comparado sem distinção entre maiúsculas e minúsculas. open usa o primeiro arquivo no corpo multipart.
resultToken é null, e resultPages é 0, quando o resultado não pode ser pré‑visualizado. downloadName é o nome do arquivo fonte com a extensão do destino.
As imagens de pré‑visualização usam a rota padrão de imagem do visualizador, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, com o token de open ou o resultToken de run. O widget solicita width=240.
Fontes carregadas são mantidas por 30 minutos após a última leitura; depois disso, run responde com 404 e o arquivo deve ser aberto novamente. downloadToken obtém sua própria janela de 30 minutos quando a conversão termina. resultToken é um token de visualizador comum para pré‑visualizar o resultado; quando o resultado pode ser pré‑visualizado, ele tem o mesmo valor que downloadToken.
| Rota | Status | Quando | Corpo |
|---|---|---|---|
| qualquer | 404 | O widget não está habilitado (AddConverterWidget() nunca foi chamado) | apenas status |
| qualquer | 405 | Verbo errado (open/run exigem POST, download requer GET) | apenas status |
open | 400 | Upload não multipart | Expected a multipart file upload. |
open | 400 | Nenhum arquivo, ou um arquivo vazio | No file uploaded. |
open | 400 | Um tipo que não pode ser convertido | This file type cannot be converted. |
open | 403 | O tipo de arquivo requer uma capacidade que a licença não concede (um arquivo DICOM sem Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | O upload excede MaxUploadMb (mas não os limites do IIS) | File is too large. |
run | 400 | Token malformado (não é um GUID) | Invalid token. |
run | 400 | Um target que não pode ser analisado para um ConversionTarget | Unknown target format. |
run | 400 | Um destino que não está em allowedTargets | That target format is not available for this file. |
run | 404 | O upload expirou ou nunca foi aberto | Upload expired — please re-open the file. |
open, run | 500 | Falha no processamento | Uma mensagem sanitizada |
download | 400 / 404 | Token de download malformado, desconhecido ou expirado | apenas status |
Uma viagem completa com fetch:
// file: o File a converter, por exemplo a partir de um <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: faça upload do arquivo
const form = new FormData();
form.append('file', file, file.name);
const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
if (!openResp.ok) throw new Error((await openResp.json()).error);
const opened = await openResp.json();
// 2. run: converta para PDF quando for permitido, caso contrário para o primeiro destino permitido
const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
'&convert=run&target=' + target, { method: 'POST' });
if (!runResp.ok) throw new Error((await runResp.json()).error);
const converted = await runResp.json();
// 3. download: um GET simples que o navegador pode seguir
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}Os endpoints são mesma origem: esta versão não tem suporte a CORS. Sirva sua UI e o script do widget a partir da mesma origem que Doconut, ou faça reverse‑proxy do manipulador e dos caminhos de recurso sob a origem da sua UI.
Em produção
- Instale o plugin ao lado do pacote principal, na mesma versão:
Install-Package Doconut.NETFramework.Converter. - Adicione o arquivo de licença. Coloque
Doconut.Viewer.Converter.licna mesma pasta queDoconut.Viewer.lic. - Defina os limites de upload.
MaxUploadMbemAddConverterWidgeté o limite que a Doconut impõe; mantenhamaxRequestLengthemaxAllowedContentLengthemWeb.configacima dele (veja Limites de upload), e omaxUploadMbdo widget igual a ele. - Nunca bloqueie em uma conversão em Web Forms (veja Em Web Forms).
- Descarte os resultados da conversão. O stream
ConvertAsyncretornado é reutilizado; descartá‑lo devolve seus buffers ao pool.
Fazendas Web
O widget mantém cada upload e seu resultado na memória no servidor que atendeu open. Por trás de um balanceador de carga sem sessões persistentes, uma solicitação posterior de run, download ou de visualização pode alcançar outro servidor e não encontrar o upload. Registre o armazenamento compartilhado e criptografado do widget através do segundo argumento de DoconutHost.Initialize:
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);
Doconut.DoconutHost.Initialize(
options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
options.AddConverterWidget();
},
services => services.AddDoconutDistributedWidgets(store =>
{
store.RootPath = @"\\fileshare\doconut"; // uma pasta que todo servidor pode ler e escrever
store.FarmKey = farmKey; // pelo menos 32 bytes, idêntico em cada servidor
// store.Ttl = TimeSpan.FromMinutes(30); // por quanto tempo um upload é mantido (o padrão)
}));- Um único servidor não precisa de nada: sem esta chamada, o armazenamento em memória é usado.
- Uploads e resultados são criptografados em repouso no compartilhamento (AES-256, encrypt-then-MAC), e cada arquivo está vinculado ao seu token, de modo que um token nunca pode ler o arquivo de outro.
- No compartilhamento, um upload ou um resultado é mantido por
Ttlapós ser escrito; lê‑lo não estende esse período. FarmKeydeve ter pelo menos 32 bytes e ser o mesmo em todos os servidores. Carregue‑lo de um armazenamento secreto; nunca o codifique diretamente. O registro lança umArgumentExceptionquandoRootPathestá ausente ouFarmKeyé menor que 32 bytes.- Aponte
RootPathpara o mesmo local compartilhado que o visualizador distribuído usa.
Referência da API
A fachada e as opções do widget estão no namespace Doconut; ConversionTarget está em Doconut.Configs.Conversion. ConverterPlugin está em Doconut.Plugins.Converter.
DocumentConverter
public sealed class DocumentConverter
{
public Task<Stream> ConvertAsync(
string filePath, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> ConvertAsync(
Stream source, string sourceExtension, ConversionTarget target,
string? password = null, CancellationToken ct = default);
public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);
public Task<Stream> HtmlToWordAsync(
Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
CancellationToken ct = default);
}Resolvido a partir de DoconutHost.Services; o construtor é interno. sourceExtension inclui o ponto inicial. HtmlToWordAsync grava um arquivo .doc quando outputFormat está ConversionTarget.Doc, e um arquivo .docx para qualquer outro valor.
ConversionTarget
Os 45 formatos de saída listados em Formatos de destino.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Definido através de DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), que retorna o DoconutOptions para que as chamadas possam ser encadeadas.
Solução de Problemas
| Sintoma | Causa | Correção |
|---|---|---|
Todas as solicitações retornam um 500 vazio após adicionar o plugin; o log de eventos do Windows (fonte ASP.NET) mostra The Converter plugin is registered via AddPlugin but no active license grants Converter. | Sem licença, um arquivo TRIAL, uma licença sem Converter, ou uma licença paga fora da sua janela de versão | Instale uma licença que conceda Converter, ou remova AddPlugin<ConverterPlugin>() |
Todas as solicitações retornam um 500 vazio; o log de eventos mostra AddConverterWidget() was called but the Converter plugin is not registered. | O widget está habilitado sem seu plugin | Adicione options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
Resolver DocumentConverter gera No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin não está registrado | Adicione AddPlugin<ConverterPlugin>() em DoconutHost.Initialize |
| Uma conversão Web Forms nunca retorna | A página bloqueia em ConvertAsync | Use Async="true" e RegisterAsyncTask |
| A conversão de fluxo indica que o formato não é suportado | sourceExtension não tem ponto inicial | Passe ".xlsx", não "xlsx" |
ConvertAsync gera Converting '.dcm' requires the Dicom capability license. | Uma fonte DICOM, e a licença não concede Dicom | Use uma licença que conceda Dicom |
| A saída tem marca d'água | A licença é temporária (Demo/NFR) | Use uma licença paga que conceda Converter |
O widget carrega mas suas solicitações retornam 404 | AddConverterWidget() não foi chamado, ou basePath não está '/DocImage.axd' | Chame AddConverterWidget(); defina basePath: '/DocImage.axd' |
| Um upload grande mostra uma página de erro do IIS ao invés da mensagem do widget | maxRequestLength / maxAllowedContentLength estão abaixo de MaxUploadMb | Aumente os limites de Web.config acima de MaxUploadMb |
open responde 403 Converting this file type requires the Dicom capability license. | Um upload DICOM, e a licença não concede Dicom | Use uma licença que conceda Dicom |
run responde 400 That target format is not available for this file. | O destino não é um dos allowedTargets da fonte | Ofereça apenas o allowedTargets de convert=open |
run ou download responde 404 (Upload expired — please re-open the file. de run) | A janela de 30 minutos expirou, ou outro servidor em um farm não tem o upload | Abra o arquivo novamente; em um farm, registre AddDoconutDistributedWidgets |
| O widget falha quando a UI está em outra origem | Os endpoints não têm suporte a CORS | Sirva a UI a partir da mesma origem, ou faça reverse-proxy nos caminhos Doconut |
| O tema não é aplicado | As variáveis são definidas em um ancestral ou em um elemento dentro da montagem; a regra .dcw própria do widget as define na montagem | Aponte para a própria montagem: #doconut-convert.dcw ou #doconut-convert |
Notas do Framework
Comparado aos pacotes ASP.NET Core, este pacote difere apenas na hospedagem; a API, o contrato de endpoint, o script do widget e as regras de licenciamento são os mesmos.
- Registro está em
Application_Start, através deDoconutHost.Initialize, ao invés debuilder.Services.AddDoconut. Serviços comoAddDoconutDistributedWidgetsvão em seu segundo argumento. - Endpoints são servidos por
DocImage.axde o script porDoconutResourceModule, ambos registrados emWeb.config, ao invés deUseDoconut()eUseDoconutResources(). O widget precisa debasePath: '/DocImage.axd'. - Falhas de inicialização aparecem como um
500vazio em cada solicitação, com o motivo no log de eventos do Windows. - Uploads são lidos completamente pelo ASP.NET antes que o Doconut os veja, portanto os limites do IIS devem estar acima de
MaxUploadMb. - Web Forms páginas não devem bloquear em uma conversão; veja Em Web Forms.
- Somente Windows, como o resto do pacote .NET Framework.
Esta página foi útil?