Plugin de conversion
Convertir des documents en 45 formats cibles
Le plugin Converter transforme Doconut en un service de conversion de documents. Il fournit le moteur derrière la façade publique DocumentConverter et — en option — un widget intégré servi par DocImage.axd, de sorte que vous pouvez convertir des documents depuis C#, depuis le widget, ou depuis une interface que vous écrivez vous‑même.
| Composant | Quand l'utiliser |
|---|---|
DocumentConverter (C#) | Vous convertissez sur le serveur, sans navigateur impliqué |
Widget intégré (doconutConverter.js) | Vous voulez un écran d'upload, de conversion et de téléchargement prêt à l'emploi dans votre page |
Points de terminaison HTTP sur DocImage.axd (?convert=open|run|download) | Vous construisez votre propre interface de conversion contre un contrat serveur documenté |
Installer le paquet
Install-Package Doconut.NETFramework.ConverterPour verrouiller le plugin à la version décrite dans cette documentation :
Install-Package Doconut.NETFramework.Converter -Version 26.10.0Conservez le paquet Converter à la même version que Doconut.NETFramework.
Le fichier de licence du plugin, Doconut.Viewer.Converter.lic, se place dans le même dossier que Doconut.Viewer.lic ; il est lu avec la licence du visualiseur.
Enregistrer le plugin
Chaque plugin s'enregistre de la même façon : AddPlugin<TPlugin>() dans DoconutHost.Initialize, appelé depuis Application_Start.
Doconut.DoconutHost.Initialize(options =>
{
options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});C’est tout ce dont la façade C# a besoin. Le widget et ses points de terminaison HTTP sont une option séparée, AddConverterWidget() (voir Widget intégré).
Le plugin nécessite une licence qui accorde la capacité Converter. Sans celle‑ci, DoconutHost.Initialize lève une exception depuis Application_Start :
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.Dans System.Web, cela signifie que chaque requête renvoie un 500 vide, et la raison n’apparaît que dans le journal d’événements Windows (source ASP.NET). Il lève une exception en l’absence de licence, avec un fichier TRIAL hérité, une licence sans Converter, ou une licence payante utilisée en dehors de sa fenêtre de version. Les licences temporaires Démo/NFR sont acceptées. Voir Configuration de la licence.
Licence & filigrane
| État de la licence | Démarrage | Résultat de la conversion |
|---|---|---|
Licence de visualisation payante accordant Converter, dans sa fenêtre de version | Démarre | Propre — watermarked: false |
| Licence temporaire active (Démo/NFR) | Démarre | Convertit, avec le filigrane d'évaluation — watermarked: true |
| Licence temporaire expirée (Démo/NFR) | Démarre | Convertit, avec le filigrane d'évaluation — watermarked: true |
Aucune licence, un fichier TRIAL hérité, une licence sans Converter, ou une licence payante hors de sa fenêtre de version | Application_Start lève une exception ; chaque requête renvoie un 500 vide | — |
La façade DocumentConverter et le gestionnaire ?convert=run du widget appliquent la même règle. Une intégration peut être construite et testée de bout en bout avec une licence d'évaluation avant l'achat — seuls les octets de sortie changent.
Une source DICOM (.dcm, .ima) nécessite également la capacité Dicom. Sans elle, ConvertAsync lève un LicenseException (Converting '.dcm' requires the Dicom capability license.) et le open du widget répond 403.
Utilisation depuis C#
Chaque conversion renvoie un MemoryStream recherchable positionné à 0. DocumentConverter est sans état : résolvez‑le depuis DoconutHost.Services où vous en avez besoin et réutilisez‑le librement.
// Résoudre DocumentConverter depuis DoconutHost.Services ; son constructeur est interne, donc ne jamais `new` cet objet.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);// sourceExtension inclut le point initial. password est nul sauf si le document est protégé.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);Stream html = await converter.WordToHtmlAsync("report.docx", ct);// html : un Stream contenant le HTML à reconvertir en document Word, comme le résultat de WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);Deux détails faciles à se tromper : sourceExtension sur la surcharge de flux doit inclure le point initial (".xlsx", pas "xlsx"), sinon il ne se résout pas. Et malgré son nom, WordToHtmlAsync renvoie Task<Stream>, pas Task<string> — le document HTML (images intégrées en Base64) arrive sous forme de flux, comme tout autre résultat.
L’appelant possède le MemoryStream qu’une conversion renvoie et doit le libérer après l’avoir copié ou renvoyé (le File(stream, …) de MVC le libère pour vous). Ne construisez ni ne libérez DocumentConverter vous‑même — son constructeur est interne.
Dans un contrôleur MVC 5
Rendez l’action asynchrone et await la conversion :
[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");
}Dans Web Forms : ne jamais bloquer une conversion
Une page Web Forms s’exécute dans un contexte de requête à thread unique. ConvertAsync reprend sur ce contexte lorsqu’il se termine, de sorte qu’une page qui attend de façon synchrone — .Result, .Wait(), .GetAwaiter().GetResult() — occupe le même thread dont la conversion a besoin pour se terminer. La requête ne renvoie jamais. Le navigateur continue de tourner, IIS n’enregistre rien, et le reste du site continue de fonctionner, de sorte que cela ressemble à une conversion lente plutôt qu’à un interblocage.
Marquez la page Async="true" et exécutez la conversion comme une tâche asynchrone de page :
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>// Web Forms : la directive @Page nécessite Async=\u0022true\u0022, et la conversion s’exécute comme une tâche asynchrone de page.
// Bloquer dessus à la place (.Result, .Wait(), .GetAwaiter().GetResult()) bloque la requête :
// cela ne renvoie jamais, et rien n’est enregistré.
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());
// Contexte, pas HttpContext.Current : après un await, ce dernier peut être nul.
Context.ApplicationInstance.CompleteRequest();
}
}));
}Sans Async="true" dans la directive @Page, RegisterAsyncTask est silencieusement ignoré. Après un await, utilisez le Context de la page ; HttpContext.Current peut être null là.
Formats cibles
ConversionTarget (espace de noms Doconut.Configs.Conversion) possède 45 membres :
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, IcoTous les formats source ne se convertissent pas en tous les formats cibles : chaque famille de formats source (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, document web, DICOM) possède son propre ensemble de cibles autorisées. Convertir une source DICOM (.dcm, .ima) nécessite également une licence qui accorde la capacité Dicom ; ses cibles sont Pdf, Png, Jpeg, Bmp, Tiff et Gif. Ne codez pas en dur cette énumération comme liste de cibles de votre interface : ?convert=open renvoie le allowedTargets du fichier téléchargé, et c’est ce qui doit alimenter le sélecteur.
Widget intégré
Activer les points de terminaison
Les points de terminaison ?convert=open|run|download du widget sont fournis par DocImage.axd et sont désactivés par défaut. Activez‑les à côté de l’enregistrement du 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 lit tout le téléchargement avant que Doconut ne le voie : conservez maxRequestLength (KB) et
// maxAllowedContentLength (octets) dans Web.config au‑dessus du MaxUploadMb du widget.AddConverterWidget() sans argument active le widget avec les valeurs par défaut (MaxUploadMb = 25). Il ne confère pas les droits de conversion à lui seul : il nécessite AddPlugin<ConverterPlugin>(), sinon DoconutHost.Initialize génère :
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.Deux choses à vérifier lorsque le widget se comporte mal :
basePath: '/DocImage.axd'. Le défaut du widget,/doconut, est le point de terminaison ASP.NET Core. Dans ce package, les points de terminaison sont le gestionnaireDocImage.axddeWeb.config.- Le script et les points de terminaison sont indépendants. Le module de ressources fournit
doconutConverter.jsque le widget soit activé ou non. SansAddConverterWidget(), le widget se charge, dessine sa zone de dépôt et apparaît parfaitement correct — et sa première action répond404.
Limites de téléchargement
ASP.NET lit le corps complet de la requête avant que DocImage.axd ne s'exécute. Un téléchargement supérieur à MaxUploadMb mais inférieur aux limites de l'hôte obtient le JSON propre au widget 413 (File is too large.). Un téléchargement supérieur aux limites de l'hôte est d'abord rejeté par IIS, avec une page d'erreur que le widget ne peut pas lire. Conservez les deux limites de l'hôte dans Web.config au-dessus de la capacité du 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>Intégrez-le
<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) prend un sélecteur CSS ou un élément, lève une exception si le point de montage n'est pas trouvé, et renvoie une poignée. Le widget téléverse un fichier, affiche un aperçu de la page 1, permet à l'utilisateur de choisir l'un des allowedTargets, convertit, prévisualise le résultat lorsqu'il le peut, et propose le téléchargement.
Options
| Option | Type | Par défaut | Remarques |
|---|---|---|---|
basePath | string | /doconut | L'URL du point de terminaison. Définissez '/DocImage.axd' sur ce paquet |
resPath | string | /doconut-res | Accepté pour la cohérence avec les autres widgets Doconut ; le widget de conversion ne construit aucune URL à partir de celui-ci |
maxUploadMb | number | 25 | Vérification préliminaire côté client uniquement ; le serveur impose sa propre limite |
licenseUrl | string | null | null | Transforme l'avis de filigrane sur l'écran de résultat en lien |
labels | object | {} | Remplace tout sous-ensemble des chaînes anglaises du widget |
Rappels
| Rappel | Se déclenche quand | Charge utile |
|---|---|---|
onReady() | Le widget a rendu son écran de dépôt | — |
onSourceLoaded({ token, pages, sourceExt, allowedTargets }) | ?convert=open réussit | Jeton source, nombre de pages, extension source (sans point initial), cibles autorisées |
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target }) | ?convert=run réussit | La réponse d'exécution plus le target demandé |
onDownload({ downloadName, downloadToken }) | L'utilisateur clique sur Télécharger | Se déclenche en même temps que le téléchargement natif du navigateur |
onError({ phase, message }) | Une requête d'ouverture ou d'exécution échoue | phase est 'open' ou 'run' ; message est l'erreur serveur sanitizée |
Un rappel qui lève une exception est intercepté et journalisé ; il ne casse jamais le flux du widget.
Gestion impérative
Doconut.convert() renvoie l'instance du widget :
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // un fichier provenant du vôtre <input type="file" id="picker">
conv.reset(); // retour à l'écran de dépôt ; ne relance pas onReady
conv.loadFile(file); // démarre le flux avec un File ; aucune opération sauf si le widget est sur son écran de dépôt
conv.destroy(); // supprime les écouteurs, vide le mount ; l'instance n'est plus utilisable après celaÉtiquettes
Chaque chaîne a une valeur par défaut en anglais ; labels remplace tout sous-ensemble et le reste reste en anglais. Les fragments qui changent à l'exécution utilisent {placeholders}, comme uploading: 'Uploading {name}…' et pages: '{n} pages'.
| Clé | Valeur par défaut en anglais |
|---|---|
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. |
D'autres clés couvrent le aria-label de la zone de dépôt (dropAriaLabel), les textes d'aperçu alt (previewAlt, resultAlt), la forme liée de l'avis de filigrane utilisé avec licenseUrl (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), une réponse illisible (badResponse) et les annonces aria-live (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError).
Une erreur JSON du serveur est affichée telle que le serveur l'a écrite ; serverError n'est utilisé que lorsqu'une réponse échouée ne contient aucune erreur JSON, comme le 404 d'un widget désactivé.
Thématisation
Le widget ajoute la classe dcw à son élément de montage et lit ses couleurs, son rayon et sa police à partir des propriétés personnalisées CSS, ainsi vous pouvez le thématiser sans toucher à son interne :
#doconut-convert.dcw {
--dcw-accent: #6b46c1;
--dcw-radius: 12px;
--dcw-font: "Inter", system-ui, sans-serif;
}Valeurs par défaut : --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px, et une police d'interface système pour --dcw-font.
Créez votre propre interface
Le widget est un client de ce contrat HTTP sur DocImage.axd. Les routes répondent 404 jusqu'à ce que AddConverterWidget() soit appelé. Les erreurs contiennent un corps JSON, { "error": "..." }, sauf lorsque le tableau indique « statut uniquement ». Une valeur ?convert= inconnue répond 400.
| Route | Objectif | Réponse réussie |
|---|---|---|
POST /DocImage.axd?convert=open (multipart, one file) | Téléverser et ouvrir un document source | 200 — { token, pages, sourceExt, allowedTargets } |
POST /DocImage.axd?token=<token>&convert=run&target=<ext> | Convertir la source téléversée en target | 200 — { downloadToken, resultToken, resultPages, downloadName, watermarked } |
GET /DocImage.axd?convert=download&token=<downloadToken> | Diffuser le fichier converti | 200 — le fichier, Content-Disposition: attachment, Cache-Control: no-store |
sourceExt dans la réponse open n'a pas de point initial ("docx") — le contraire du paramètre sourceExtension de ConvertAsync. allowedTargets répertorie les noms de cibles en minuscules ("pdf", "html", …) ; transmettez‑en un comme target, qui est comparé sans tenir compte de la casse. open utilise le premier fichier du corps multipart.
resultToken est null, et resultPages est 0, lorsque le résultat ne peut pas être prévisualisé. downloadName est le nom du fichier source avec l'extension de la cible.
Les images de prévisualisation utilisent la route d'image du visualiseur standard, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, avec le token provenant de open ou le resultToken provenant de run. Le widget demande width=240.
Les sources téléversées sont conservées pendant 30 minutes après leur dernière lecture ; après cela, run répond 404 et le fichier doit être ouvert à nouveau. downloadToken bénéficie de sa propre fenêtre de 30 minutes lorsque la conversion se termine. resultToken est un jeton de visualiseur ordinaire pour prévisualiser le résultat ; lorsque le résultat peut être prévisualisé, il a la même valeur que downloadToken.
| Route | Statut | Quand | Corps |
|---|---|---|---|
| tout | 404 | Le widget n'est pas activé (AddConverterWidget() n'a jamais été appelé) | statut uniquement |
| tout | 405 | Verbe incorrect (open/run nécessitent POST, download nécessite GET) | statut uniquement |
open | 400 | Pas un téléversement multipart | Expected a multipart file upload. |
open | 400 | Pas de fichier, ou un fichier vide | No file uploaded. |
open | 400 | Un type qui ne peut pas être converti | This file type cannot be converted. |
open | 403 | Le type de fichier nécessite une capacité que la licence n'accorde pas (un fichier DICOM sans Dicom) | Converting this file type requires the Dicom capability license. |
open | 413 | Le téléversement dépasse MaxUploadMb (mais pas les limites IIS) | File is too large. |
run | 400 | Un jeton malformé (pas un GUID) | Invalid token. |
run | 400 | Un target qui ne se convertit pas en ConversionTarget | Unknown target format. |
run | 400 | Une cible non présente dans allowedTargets | That target format is not available for this file. |
run | 404 | Le téléversement a expiré ou n'a jamais été ouvert | Upload expired — please re-open the file. |
open, run | 500 | Traitement échoué | Un message assaini |
download | 400 / 404 | Un jeton de téléchargement malformé, inconnu ou expiré | statut uniquement |
Un parcours complet avec fetch :
// file: le fichier à convertir, par exemple depuis un <input type="file">.
async function convertFile(file) {
const base = '/DocImage.axd';
// 1. open: téléverser le fichier
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: convertir en PDF lorsqu'il est autorisé, sinon vers la première cible autorisée
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: un simple GET que le navigateur peut suivre
window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}Les points de terminaison sont même‑origine : cette version ne prend pas en charge CORS. Servez votre interface utilisateur et le script du widget depuis la même origine que Doconut, ou reverse-proxy le gestionnaire et les chemins de ressources sous l'origine de votre interface.
En production
- Installez le plugin à côté du package principal, à la même version :
Install-Package Doconut.NETFramework.Converter. - Ajoutez le fichier de licence. Placez
Doconut.Viewer.Converter.licdans le même dossier queDoconut.Viewer.lic. - Définissez les plafonds de téléchargement.
MaxUploadMbdansAddConverterWidgetest la limite imposée par Doconut ; maintenezmaxRequestLengthetmaxAllowedContentLengthdansWeb.configau‑dessus de celle‑ci (voir Limites de téléchargement), et lemaxUploadMbdu widget égal à celle‑ci. - Ne bloquez jamais lors d’une conversion dans Web Forms (voir Dans Web Forms).
- Libérez les résultats de conversion. Le flux
ConvertAsyncrenvoyé est mis en pool ; le libérer renvoie ses tampons au pool.
Fermes Web
Le widget conserve chaque téléchargement et son résultat en mémoire sur le serveur qui a servi open. Derrière un équilibreur de charge sans sessions persistantes, une requête ultérieure run, download ou de prévisualisation peut atteindre un autre serveur et ne pas trouver le téléchargement. Enregistrez le magasin partagé et chiffré du widget via le deuxième argument 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"; // un dossier que chaque serveur peut lire et écrire
store.FarmKey = farmKey; // au moins 32 bytes, identique sur chaque serveur
// store.Ttl = TimeSpan.FromMinutes(30); // durée pendant laquelle un téléchargement est conservé (par défaut)
}));- Un serveur unique n’a besoin de rien : sans cet appel, le magasin en mémoire est utilisé.
- Les téléchargements et les résultats sont chiffrés au repos sur le partage (AES‑256, encrypt‑then‑MAC), et chaque fichier est lié à son jeton, de sorte qu’un jeton ne peut jamais lire le fichier d’un autre.
- Sur le partage, un téléchargement ou un résultat est conservé pendant
Ttlaprès son écriture ; le lire n’allonge pas cette période. FarmKeydoit faire au moins 32 octets et être identique sur chaque serveur. Chargez‑le depuis un magasin secret ; ne le codez jamais en dur. L’enregistrement lève unArgumentExceptionlorsqueRootPathest manquant ou queFarmKeyfait moins de 32 octets.- Pointez
RootPathvers le même emplacement partagé utilisé par le visualiseur distribué.
Référence API
La façade et les options du widget se trouvent dans l’espace de noms Doconut ; ConversionTarget se trouve dans Doconut.Configs.Conversion. ConverterPlugin se trouve dans 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);
}Résolu à partir de DoconutHost.Services ; le constructeur est interne. sourceExtension inclut le point initial. HtmlToWordAsync écrit un fichier .doc lorsque outputFormat est ConversionTarget.Doc, et un fichier .docx pour toute autre valeur.
ConversionTarget
Les 45 formats de sortie répertoriés dans Formats cibles.
ConverterWidgetOptions
public sealed class ConverterWidgetOptions
{
public int MaxUploadMb { get; set; } = 25;
}Défini via DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null), qui renvoie le DoconutOptions afin que les appels puissent être enchaînés.
Dépannage
| Symptôme | Cause | Correction |
|---|---|---|
Chaque requête renvoie un 500 vide après avoir ajouté le plugin ; le journal d'événements Windows (source ASP.NET) indique The Converter plugin is registered via AddPlugin but no active license grants Converter. | Pas de licence, un fichier TRIAL, une licence sans Converter, ou une licence payante en dehors de sa fenêtre de version | Installez une licence qui accorde Converter, ou supprimez AddPlugin<ConverterPlugin>() |
Chaque requête renvoie un 500 vide ; le journal d'événements indique AddConverterWidget() was called but the Converter plugin is not registered. | Le widget est activé sans son plugin | Ajoutez options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() |
La résolution de DocumentConverter génère No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). | ConverterPlugin n'est pas enregistré | Ajoutez AddPlugin<ConverterPlugin>() dans DoconutHost.Initialize |
| Une conversion Web Forms ne renvoie jamais | La page se bloque sur ConvertAsync | Utilisez Async="true" et RegisterAsyncTask |
| La conversion de flux indique que le format n'est pas pris en charge | sourceExtension n'a pas de point initial | Passez ".xlsx", pas "xlsx" |
ConvertAsync génère Converting '.dcm' requires the Dicom capability license. | Une source DICOM, et la licence n'accorde pas Dicom | Utilisez une licence qui accorde Dicom |
| La sortie est filigranée | La licence est temporaire (Démo/NFR) | Utilisez une licence payante qui accorde Converter |
Le widget se charge mais ses requêtes renvoient 404 | AddConverterWidget() n'a pas été appelé, ou basePath n'est pas '/DocImage.axd' | Appelez AddConverterWidget() ; définissez basePath: '/DocImage.axd' |
| Un gros téléchargement affiche une page d'erreur IIS au lieu du message du widget | maxRequestLength / maxAllowedContentLength sont en dessous de MaxUploadMb | Augmentez les limites de Web.config au-dessus de MaxUploadMb |
open répond 403 Converting this file type requires the Dicom capability license. | Un téléchargement DICOM, et la licence n'accorde pas Dicom | Utilisez une licence qui accorde Dicom |
run répond 400 That target format is not available for this file. | La cible n'est pas l'un des allowedTargets de la source | Proposez uniquement le allowedTargets de convert=open |
run ou download répond 404 (Upload expired — please re-open the file. de run) | La fenêtre de 30 minutes est écoulée, ou un autre serveur du farm ne possède pas le téléchargement | Rouvrez le fichier ; dans un farm, enregistrez AddDoconutDistributedWidgets |
| Le widget échoue lorsque l'UI est sur une autre origine | Les points de terminaison n'ont pas de support CORS | Servez l'UI depuis la même origine, ou utilisez un reverse-proxy sur les chemins Doconut |
| Le thème ne s'applique pas | Les variables sont définies sur un ancêtre ou sur un élément à l'intérieur du montage ; la règle .dcw du widget les définit sur le montage | Ciblez le montage lui‑même : #doconut-convert.dcw ou #doconut-convert |
Notes du framework
Par rapport aux packages ASP.NET Core, ce package ne diffère que par l'hébergement ; l'API, le contrat des points de terminaison, le script du widget et les règles de licence sont les mêmes.
- Enregistrement se fait dans
Application_Start, viaDoconutHost.Initialize, au lieu debuilder.Services.AddDoconut. Les services tels queAddDoconutDistributedWidgetssont placés dans son deuxième argument. - Points de terminaison sont servis par
DocImage.axdet le script parDoconutResourceModule, tous deux enregistrés dansWeb.config, au lieu deUseDoconut()etUseDoconutResources(). Le widget nécessitebasePath: '/DocImage.axd'. - Échecs de démarrage apparaissent sous la forme d'un
500vide à chaque requête, la raison étant indiquée dans le journal d'événements Windows. - Téléversements sont lus en entier par ASP.NET avant que Doconut ne les voie, donc les limites IIS doivent être supérieures à
MaxUploadMb. - Pages Web Forms ne doivent pas se bloquer sur une conversion ; voir Dans Web Forms.
- Windows uniquement, comme le reste du package .NET Framework.
Cette page était-elle utile ?