Visual Studio Code extension for accessing Autodesk Platform Services services and content.
Note: Autodesk Forge is now Autodesk Platform Services but you may still see the Forge brand used in different areas of this extension. These references have been kept to maintain backwards compatibility.
- Visual Studio Code version 1.92.0 or newer
- APS app credentials (tutorial)
- If you plan to sign in with 3-legged OAuth (see Authentication), your APS app
must have
vscode://petrbroz.vscode-forge-tools/callbackregistered as a callback URL on https://aps.autodesk.com/myapps - without it, sign-in will fail with a redirect URI mismatch.
While in Visual Studio Code:
- Switch to the Extensions sidebar (
Cmd+Shift+Xon macOS orCtrl+Shift+Xon Windows), search for the Autodesk Platform Services extension, and install it.
- When you activate the Autodesk Platform Services extension for the first time, it'll guide you through creating your first "environment". An environment is basically a configuration for a specific APS application, including its client ID and secret, or region, for example.
You can configure additional environments or update existing ones by going to User Settings (
Cmd+,on macOS orCtrl+,on Windows), searching for autodesk environments, clicking the Edit in settings.json link, and modifying the JSON settings manually. Switch to User or Workspace tab depending on whether you want to persist the settings globally (for all instances of the editor) or locally (only for a specific workspace).
The extension exposes the following settings:
autodesk.forge.environments- array of objects representing different APS applications or "environments"; each environment can specify the following properties:title(required) - unique name of the environment (will be shown in the status bar and listed when switching between other environments)clientId(required) - APS client IDclientSecret(required) - APS client secretregion- data region for storing design data; can beUS(default),EMEA,AUS,CAN,DEU,IND,JPN, orGBR
autodesk.forge.data.defaultContentType- content type to use for all files uploaded to OSSautodesk.forge.data.uploadChunkSize- size of individual chunks (in bytes) when uploading files to OSS with the resumable functionalityautodesk.forge.viewer.extensions- array of Viewer extension IDs (for example,Autodesk.VisualClustersorAutodesk.DocumentBrowser) to be automatically loaded when previewing derivativesautodesk.forge.viewer.api- Model Derivative API used by the viewer; by default, the viewer will determine the appropriate API based on the viewable output format (SVF vs SVF2)autodesk.forge.viewer.env- Model Derivative environment used by the viewer; by default, the viewer will determine the appropriate environment based on the viewable output format (SVF vs SVF2)
Here's an example of how the extension settings might look like in the JSON format:
If you have configured multiple APS environments, you can switch between them via the status bar at the bottom, or using the aps.switchEnvironment command from the Command Palette. The extension will always initialize itself based on the first environment in the list.
Note: if you have configured the extension both in the User scope and in the Workspace scope, the extension will present the list of environments from the Workspace scope as it has higher precedence.
Plain 2-legged (app) access is always available by default, and backs every "(app)" view below. Views and commands that need a user context — Data & Derivatives (user), Issues (user), and Webhooks (user) — show a "Sign in to APS" welcome button until you're signed in; you can also sign in via the aps.auth.login command or the VS Code Accounts menu. Signing in offers a choice of 3-legged OAuth (confidential client), 3-legged OAuth with PKCE (public client, no secret), a Secure Service Account (sign in on behalf of a service account using its private key), or pasting an access token obtained from another APS application. Sessions are persisted per environment in VS Code's encrypted secret storage, so they survive a window reload, and 3-legged/PKCE tokens are refreshed automatically. Once signed in, use the "Logout" action in the title bar of any user-context view (or the aps.auth.logout command) to sign out again.
Important: the 3-legged OAuth flows ("3-legged OAuth" and "3-legged OAuth with PKCE") redirect back into VS Code via a
vscode://petrbroz.vscode-forge-tools/callbackURI (resolved throughvscode.env.asExternalUri, so it also works in remote/SSH, Codespaces, and vscode.dev). You must register this URL - or, when working in a remote/web context, whatever URLvscode.env.asExternalUriresolves it to - as a callback URL for your application on https://aps.autodesk.com/myapps, or sign-in will fail. The extension will also show you this URL, with a "Copy URL" action, the first time you use one of these sign-in methods.
The Data & Derivatives (app) view allows you to browse Data Management OSS (object simple storage) content, create buckets, upload & download files, translate them using the Model Derivative service, and even preview the generated derivatives in a custom editor tab. All derivatives are listed as children of their corresponding objects in the tree. If there are no derivatives yet, or if there's been an issue with the translation, the tree view will provide additional information.
Here's some actions you can try:
- Create a new bucket to store your designs.
Note that bucket names must be globally unique. If you see a
409 Conflicterror, you'll need to choose a different name.
- Upload a design to your bucket.
- Translate the design for viewing.
- Preview design derivatives in a new editor tab.
Similar to the Data & Derivatives (app) view, but using a signed-in user context instead, allowing you to browse your existing design data hosted in BIM 360, ACC, and other products built with the Autodesk Platform Services. See Authentication above for how to sign in.
The Issues (user) view lets you browse ACC/BIM 360 issues in a hub → project → issue tree, and open a details panel for an individual issue that also lists its comments, if any. Requires the same signed-in user context as the other "(user)" views.
The Webhooks (app) and Webhooks (user) views can be used to browse and manage app-owned and user-owned webhooks, respectively, in the Webhooks service, across all supported webhook systems (Data Management, Model Derivative, Cost Management, Forma Issues, Forma Reviews, Autodesk Tandem, and more).
The Design Automation (app) view can be used for browsing Design Automation entities such as app bundles and activities, creating and updating them, and submitting work items against an activity. It also provides a context menu that can be used to view additional details of individual bundles or activities.
Manage your Secure Service Accounts and their keys through the Secure Service Accounts (app) view and the context menu of individual tree items — including generating assertions and access tokens for a key — or use any commands starting with Secure Service Accounts:.
The Model Derivative service lets you store derivatives in a region of your choice. In our code we always assume that the derivatives are stored in the same region as the input object. Note that this can cause issues, for example, when you use the Translate Object or Translate Object (Custom) command on an object for which the derivatives are already available in another region. In that case you will get an error with status code 406, and you will need to delete the derivatives manually (using the Delete Derivatives command) before being able to translate the object again.
- clone the repository
- install and setup dependencies:
yarn install - open the project in vscode and launch the Launch Extension task; new vscode window will open
- make sure you have at least one set of APS credentials configured (see Getting Started and Extension Settings)
- click on the APS icon in the sidebar and start browsing
When debugging a webview inside vscode, use the
Developer: Open Webview Developer Toolsand theDeveloper: Reload Windowcommands.
VSCode seems to be caching different HTTP requests made by the viewer, and when you try and preview a design that's been re-translated, the viewer may get a cached manifest JSON that's outdated. Unfortunately the only solution I've found for this is to clear any VSCode cache: https://theblogreaders.com/visual-studio-code-tip-cleanup-cache-folder-better-performance.