API reference
A curated map of the surfaces you will actually use, with the full generated class reference for everything else.
Server
| Surface | What it does |
|---|---|
AddCoreUpload(options) | Registers services; configures MaxFileSizeBytes, AllowedExtensions, temp directory, cleanup, providers. |
MapCoreUploadEndpoints() | Maps /upload, /upload/multiple, /chunk, /chunk/complete, /chunk/status, /tus, /s3/*, /azure/*, /gcs/*, progress, info, download, delete. |
IUploadService | Your app's handle on stored files: GetFileInfoAsync, OpenFileAsync, MoveFileAsync, CopyFileAsync, DeleteFileAsync, ValidateFile. |
IUploaderProvider | Storage abstraction (filesystem ships in-box). Implement to store uploads anywhere. |
IS3Signer / IAzureSigner / IGcsSigner | Direct-to-cloud signing with your SDK and credentials. Guide. |
IUploadEventHandler | Server-side hooks: validate before storage, react after (OnFileValidatingAsync, OnFileUploadedAsync). |
Tag Helper: the attributes you reach for first
| Attribute | Purpose |
|---|---|
asp-upload-url | Endpoint base (the one you mapped). |
asp-multiple, asp-auto-upload | Multi-select; start on selection vs on demand. |
asp-chunked, asp-chunk-size, asp-chunk-concurrency | Large-file transport tuning. |
asp-strategy | chunked | s3 | azure | gcs | tus | custom. |
asp-extensions, asp-max-size, asp-mime-types | Client-side validation (server re-validates). |
asp-drop-zone, asp-full-page-drop, asp-directory | Drag-and-drop and folder upload. |
asp-persist-state, asp-persist-adapter, asp-persist-blobs | Cross-session resume (IndexedDB). Demo. |
asp-hidden-input-id | Hidden field of completed GUIDs for form posts. Guide. |
asp-compute-hash, asp-hash-algorithm | Client-side checksums (CRC32/SHA-256) sent with the upload. |
asp-meta-fields | Per-file editable metadata submitted with the file. |
Every Tag Helper attribute
The full set the Tag Helper accepts — 71 attributes. Defaults are shown where one applies.
Endpoints
| Attribute | Default | Purpose |
|---|---|---|
asp-upload-url | — | Endpoint base — the prefix you passed to MapCoreUploadEndpoints(). |
asp-chunk-url | — | Chunk endpoint. Defaults to {RoutePrefix}/chunk. |
asp-chunk-complete-url | — | Chunk-completion endpoint. Defaults to the chunk URL plus /complete. |
asp-delete-url | — | Endpoint called when a queued file is removed. |
asp-tus-endpoint | — | tus 1.0 endpoint. Defaults to {uploadUrl base}/tus. |
asp-with-credentials | false | Send cookies and HTTP auth on cross-origin upload requests. |
asp-antiforgery | false | Send the ASP.NET Core antiforgery token with every upload request, as the header named by AntiforgeryOptions.HeaderName (default RequestVerificationToken). Independent of the server switch: set CoreUploadOptions.EnableAntiforgery to make the endpoints validate it. Needs AddAntiforgery() registered; without it this attribute does nothing rather than throwing. |
Transport and strategy
| Attribute | Default | Purpose |
|---|---|---|
asp-strategy | auto | auto, single, chunked, s3, azure, gcs, tus or urlImport. |
asp-chunked | false | Split files into chunks instead of one request. |
asp-chunk-size | — | Chunk size in bytes. |
asp-chunk-concurrency | — | Chunks or parts uploaded in parallel for multipart transports. |
asp-prioritize-first-last-chunk | false | Upload chunk 0 and the final chunk first, so the server can validate a container header early. |
asp-concurrent | — | How many files upload at once. |
asp-compute-hash | false | Compute a content hash off-thread in a Web Worker. |
asp-hash-algorithm | — | Hash used when asp-compute-hash is on — crc32 or sha256. |
Selection and limits
| Attribute | Default | Purpose |
|---|---|---|
asp-multiple | false | Allow selecting more than one file. |
asp-auto-upload | true | Start on selection rather than on an explicit upload click. |
asp-directory | false | Select a whole folder tree (webkitdirectory). |
asp-max-files | — | Maximum number of files selectable. |
asp-max-count | — | Maximum number of files retained in the queue. |
asp-max-size | — | Maximum file size, e.g. 25MB. |
asp-min-size | — | Minimum file size. |
asp-extensions | — | Comma-separated allowed extensions. |
asp-mime-types | — | Comma-separated allowed MIME types, checked against magic bytes. |
asp-detect-duplicates | false | Reject a file already in the queue, matched by content. |
asp-preloaded-files | — | JSON array of files already stored, rendered into the queue on load. |
asp-meta-fields | — | JSON array of per-file editable metadata fields. |
Image pipeline
| Attribute | Default | Purpose |
|---|---|---|
asp-crop | false | Open the inline crop editor after selection. |
asp-crop-aspect-ratio | — | Lock the crop to a ratio, e.g. 1:1 or 16:9. |
asp-resize-max-width | — | Downscale wider images before upload. |
asp-resize-max-height | — | Downscale taller images before upload. |
asp-resize-quality | — | Re-encode quality, 0–1. |
asp-resize-format | — | Output format — jpeg, webp or avif. |
asp-auto-orient | false | Apply the EXIF orientation so rotated photos upload upright. |
asp-renditions | — | JSON array of scaled renditions generated alongside each image. |
asp-min-width | — | Reject images narrower than this. |
asp-min-height | — | Reject images shorter than this. |
asp-max-width | — | Reject images wider than this. |
asp-max-height | — | Reject images taller than this. |
Input sources
| Attribute | Default | Purpose |
|---|---|---|
asp-paste | true | Accept images and files pasted from the clipboard. |
asp-drop-zone | true | Render the built-in drop zone. |
asp-drop-target | — | CSS selector of your own element to use as the drop target instead. |
asp-full-page-drop | false | Accept a drop anywhere on the page, with a full-window overlay. |
asp-drop-overlay-text | — | Overlay caption shown during a full-page drag. |
asp-remote-sources | — | Comma-separated cloud sources: googledrive, dropbox, onedrive, box, unsplash, companion. |
Resume and cross-tab
| Attribute | Default | Purpose |
|---|---|---|
asp-persist-state | false | Persist in-flight uploads so a reload or crash resumes them. |
asp-persist-adapter | — | Where state lives — localStorage or indexeddb. |
asp-persist-key | — | Storage key, when one page hosts several uploaders. |
asp-persist-blobs | false | Also persist the file bytes, so resume survives a browser restart. Requires the IndexedDB adapter. |
asp-cross-tab | false | Coordinate uploads across tabs so the same file is not sent twice. |
asp-cross-tab-channel | — | BroadcastChannel name used for that coordination. |
Appearance
| Attribute | Default | Purpose |
|---|---|---|
asp-button-text | Select Files | Label on the browse button. Left unset, it follows the active locale. |
asp-button-label | Select files | Accessible name used when asp-button-text is empty (icon-only buttons). |
asp-upload-button-text | Upload | Label on the manual upload button. |
asp-button-class | — | Extra CSS classes for the browse button. |
asp-browse-button | — | CSS selector of your own button; the built-in one is hidden. |
asp-inline | false | Lay the uploader out inline rather than as a block. |
asp-progress | true | Render the progress bar. |
asp-queue | true | Render the file queue. |
asp-thumbnails | true | Render image thumbnails in the queue. |
asp-gallery | false | Open completed images in a lightbox. |
asp-sortable | false | Let the user drag queue items to reorder them. |
asp-keyboard-navigation | true | Deep keyboard navigation of the queue. |
asp-hidden-input-id | — | Id of a hidden input to receive the uploaded file references for a normal form post. |
Client-side events
| Attribute | Default | Purpose |
|---|---|---|
asp-on-select | — | JavaScript called when files are selected. |
asp-on-progress | — | Overall queue progress. |
asp-on-complete | — | The whole queue finished. |
asp-on-error | — | An upload failed. |
asp-on-task-complete | — | One file finished. |
asp-on-task-error | — | One file failed. |
asp-on-rendition-created | — | A scaled rendition was generated. |
Deprecated aliases
| Attribute | Use instead |
|---|---|
asp-folder-drop | asp-directory |
asp-drop-overlay | asp-full-page-drop |
JavaScript: instance + events
const u = CoreUpload.create('#host', { uploadUrl: '/api/upload/upload', chunked: true });
// or grab a Tag-Helper-rendered instance:
const u2 = CoreUpload.getInstance('my-uploader-id');
u.on('taskProgress', t => ...); // per-file progress/speed/eta
u.on('taskComplete', (t, result) => ...); // result.fileGuid, result.url
u.on('taskError', (t, message) => ...);
u.on('complete', files => ...); // whole queue finished
u.addFiles(files); u.upload(); u.pauseAll(); u.resumeAll(); u.cancelAll(); u.destroy();The full option list ships as a TypeScript definition (coreupload.d.ts) in the package — your editor autocompletes it.