Citolab.QTI.Uploader 0.2.5

dotnet add package Citolab.QTI.Uploader --version 0.2.5
                    
NuGet\Install-Package Citolab.QTI.Uploader -Version 0.2.5
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Citolab.QTI.Uploader" Version="0.2.5" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Citolab.QTI.Uploader" Version="0.2.5" />
                    
Directory.Packages.props
<PackageReference Include="Citolab.QTI.Uploader" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Citolab.QTI.Uploader --version 0.2.5
                    
#r "nuget: Citolab.QTI.Uploader, 0.2.5"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Citolab.QTI.Uploader@0.2.5
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Citolab.QTI.Uploader&version=0.2.5
                    
Install as a Cake Addin
#tool nuget:?package=Citolab.QTI.Uploader&version=0.2.5
                    
Install as a Cake Tool

Citolab.QTI.Converter and Citolab.QTI.Uploader

Small .NET library that:

  • validates and extracts QTI package zip files
  • optionally converts QTI 2.x packages to QTI 3 (via pluggable converter)
  • streams the original zip and extracted entries to a consumer-provided callback (e.g. Blob Storage)

Packages / projects

  • Citolab.QTI.Uploader: core uploader abstractions + zip extraction
  • Citolab.QTI.Converter: optional (pure .NET) converter implementation that converts QTI 2.x packages to QTI 3

NuGet publishing (GitHub Actions)

This repo includes a GitHub Actions workflow at .github/workflows/nuget.yml that builds/tests/packs on PRs and on pushes to main, and publishes to NuGet.org on:

  • a tag push like v0.1.0 (uses the tag as the NuGet version), or
  • a manual run (Actions → workflow → Run workflow) with an optional version input.

Publishing uses nuget.org Trusted Publishing: the workflow exchanges a GitHub OIDC token for an API key that is valid for one hour, so no API key is stored. To enable it:

  • on nuget.org, under your username → Trusted Publishing, add a policy for repository owner Citolab, repository qti-convert-dotnet, workflow file nuget.yml (no environment), owned by the account or organization that owns the packages;
  • add NUGET_USER as a repository secret: the nuget.org profile name of that owner (not an email address).

Basic usage (ASP.NET Controller)

Create an IQtiPackageStore that uploads to your storage, then call QtiPackageUploader.UploadAsync(...).

QTI 2.x → QTI 3 conversion

If you want automatic conversion for QTI 2.x packages, configure QtiUploaderOptions:

using Citolab.QTI.Converter;
using Citolab.QTI.Uploader;

var uploader = new QtiPackageUploader();
var options = new QtiUploaderOptions
{
    ConvertQti2ToQti3 = true,
    Converter = new Qti2ToQti3PackageConverter(
        new Qti2ToQti3PackageConverterOptions
        {
            ItemTransformOptions = new QtiItemTransformOptions
            {
                // These are enabled by default; set to false to disable.
                ObjectToImg = true,
                ObjectToVideo = true,
                ObjectToAudio = true,
                SsmlSubToSpan = true,
                StripMaterialInfo = true,
                MinChoicesToOne = true,
                ExternalScored = true,

                // Optional extras (off by default).
                QbCleanup = false,
                DepConvert = false,
                UpgradePci = false,
                StripStylesheets = false
            },

            // Optional per-item hook for consumer-specific transformations.
            OnItemTransformedAsync = async (transform, itemPath, ct) =>
            {
                // Example: add a marker attribute
                await transform.FnChAsync(doc =>
                {
                    doc.Root?.SetAttributeValue("data-processed-by", "my-app");
                    return Task.CompletedTask;
                });
            }
        })
};

The QTI 2.x → QTI 3 conversion is plain .NET (System.Xml.Linq, no XSLT processor or other dependencies) and behaves the same on net9.0 and netstandard2.0. It is a port of the qti2xTo30.xsl upgrader and is tested against that XSLT's recorded output.

QTI 3 → QTI 2.1 conversion

Qti3ToQti21PackageConverter converts a QTI 3 package back to QTI 2.1 (best-effort). Constructs without a QTI 2.1 equivalent are converted or removed and reported as warnings:

  • shared stimuli are inlined into the items that reference them (and removed from the package and manifest)
  • HTML5 audio/video become object, an img in graphic interactions becomes the required object, and a gap text with only an image becomes a gapImg
  • a PCI is wrapped in a customInteraction; data-*, aria-*, role, dir and SSML are removed
  • HTML5-only elements (section, figure, ruby, ...) become div/span
  • items that use QTI 3 shared vocabulary classes (qti-layout-row, qti-underline, ...) get a stylesheet to qti3-shared-vocabulary.css, which is added next to the manifest and registered in it (InjectSharedVocabularyStylesheet, default on). It holds the 1EdTech qti3p0.css utility classes, with its page-level layout section replaced by a grid sized by the row, plus fixes for QTI 2.1 players
using Citolab.QTI.Converter;

var converter = new Qti3ToQti21PackageConverter();
var result = await converter.ConvertQti3PackageToQti21Async("package.zip", cancellationToken); // writes package-qti21.zip
foreach (var warning in result.Warnings) Console.WriteLine(warning);

// or with streams
var warnings = await converter.ConvertAsync(inputStream, outputStream, cancellationToken);

// or a single file
var item = Qti3ToQti21XmlConverter.Convert(qti3Xml);

The item, test and manifest conversions can be replaced via Qti3ToQti21PackageConverterOptions (ConvertItem, ConvertAssessment, ConvertManifest). The output is tested against the official QTI 2.1 XSD.

Item transformations

When converting an assessment item, the converter can apply a set of optional XML transformations via QtiTransform and QtiItemTransformOptions.

Default item transforms (enabled by default)

  • ObjectToImg: converts <object type="image/*" data="...">ALT</object> to <img src="..." alt="ALT" .../>.
  • ObjectToVideo: converts <object type="video/*" ... data="..."> to <video><source .../></video> and normalizes existing <video controls> usage.
  • ObjectToAudio: converts <object type="audio/*" ... data="..."> to <audio><source .../></audio> and normalizes existing <audio controls> usage.
  • SsmlSubToSpan: converts SSML elements (e.g. <ssml:sub>, <ssml:break>, <ssml:say-as>, etc.) to <span> elements with data-ssml-* attributes.
  • StripMaterialInfo: removes <qti-companion-materials-info>.
  • MinChoicesToOne: ensures <qti-choice-interaction min-choices> is at least 1.
  • ExternalScored: when there is no <qti-response-processing>, sets external-scored="human" on the SCORE outcome declaration.

Additional item transforms (disabled by default)

  • QbCleanup: cleanup for common Question Builder (QB) HTML-ish wrappers (unwraps some <div> wrappers, span cleanup, etc.).
  • DepConvert: converts Dutch Extension Profile dialog triggers (.dep-dialogTrigger) into HTML popover buttons.
  • DepConvertExtended: converts DEP dialogs into a <dep-popup> structure (trigger + popup slot).
  • HideInputsForChoiceInteractionWithImages: adds qti-input-control-hidden when all choices contain images.
  • UpgradePci: upgrades TAO-exported portable custom interactions into a structure expected by QTI components (moves properties to data-*, normalizes modules/markup, etc.).
  • StripStylesheets: removes <qti-stylesheet> nodes; supports wildcard matching via StripStylesheetsRemovePattern / StripStylesheetsKeepPattern.
  • StylesheetsInlineAsync: fetches CSS content from external stylesheet URLs and inlines them into <qti-stylesheet> elements. Supports both HTTP URLs and relative file paths within QTI packages. Use OnItemTransformedAsync hook for custom async transformations like this.

Usage example for StylesheetsInlineAsync with ZIP uploads:

OnItemTransformedAsync = async (transform, itemPath, fileResolver, ct) =>
{
    // Inline external stylesheets from ZIP package files
    await transform.StylesheetsInlineAsync(async (resolvedPath, currentItemPath) =>
    {
        // resolvedPath is the stylesheet path resolved relative to the item
        // Use the provided fileResolver to get CSS content from ZIP package
        return await fileResolver(resolvedPath);
    }, itemPath);
    
    // Alternative: if stylesheets are HTTP URLs, use custom HTTP client
    await transform.StylesheetsInlineAsync(async href => {
        if (href.StartsWith("http"))
        {
            using var client = new HttpClient();
            var response = await client.GetAsync(href, ct);
            return response.IsSuccessStatusCode 
                ? await response.Content.ReadAsStringAsync() 
                : null;
        }
        // For relative paths, use the ZIP file resolver
        var resolvedPath = Path.Combine(Path.GetDirectoryName(itemPath) ?? "", href.Replace('/', Path.DirectorySeparatorChar));
        return await fileResolver(resolvedPath.Replace('\\', '/'));
    });
}

Example QTI Package Structure:

item1/
  ├── question.xml          (contains <qti-stylesheet href="../shared/styles.css">)
  └── item-specific.css
shared/
  └── styles.css            (CSS file to be inlined)

When processing item1/question.xml, the stylesheet ../shared/styles.css resolves to shared/styles.css in the ZIP package.

Consumer hook

  • Qti2ToQti3PackageConverterOptions.OnItemTransformedAsync runs per assessment item after the built-in transforms, and receives a mutable QtiTransform so you can call .FnCh(...) / .FnChAsync(...) or chain additional built-ins.

License

GPL-3.0-only, see LICENSE. The QTI 2 → QTI 3 conversion is a port of the qti2xTo30.xsl upgrader by ETS (Apache-2.0); the shared vocabulary stylesheet contains the 1EdTech QTI 3 shared css utility classes.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 is compatible.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • .NETStandard 2.0

    • No dependencies.
  • net9.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Citolab.QTI.Uploader:

Package Downloads
Citolab.QTI.Converter

.NET QTI package converter for Citolab.QTI.Uploader: QTI 2.x to QTI 3, and QTI 3 back to QTI 2.1. Pure .NET, no XSLT processor.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.2.5 119 11/18/2026
0.2.4 258 10/23/2026
0.2.3 201 10/15/2026
0.2.2 533 9/29/2026
0.2.1 162 9/23/2026
0.2.0 142 9/23/2026
0.1.1 687 6/5/2026
0.1.0 381 1/26/2026