Skip to content

petrbroz/vscode-forge-tools

Repository files navigation

Autodesk Platform Services (VSCode Extension)

Visual Studio Marketplace Version Visual Studio Marketplace Installs Visual Studio Marketplace Downloads platforms license

Visual Studio Code extension for accessing Autodesk Platform Services services and content.

Preview

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.

Requirements

Installation

While in Visual Studio Code:

  1. Switch to the Extensions sidebar (Cmd+Shift+X on macOS or Ctrl+Shift+X on Windows), search for the Autodesk Platform Services extension, and install it.

Install extension

  1. 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.

Setup extension

You can configure additional environments or update existing ones by going to User Settings (Cmd+, on macOS or Ctrl+, 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).

Extension Settings

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 ID
    • clientSecret (required) - APS client secret
    • region - data region for storing design data; can be US (default), EMEA, or APAC
  • autodesk.forge.authentication.port - server port to use during 3-legged authentication workflows
  • autodesk.forge.data.defaultContentType - content type to use for all files uploaded to OSS
  • autodesk.forge.data.uploadChunkSize - size of individual chunks (in bytes) when uploading files to OSS with the resumable functionality
  • autodesk.forge.viewer.extensions - array of Viewer extension IDs (for example, Autodesk.VisualClusters or Autodesk.DocumentBrowser) to be automatically loaded when previewing derivatives
  • autodesk.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:

Extension Settings

Features

Multiple Environments

If you have configured multiple APS environments, you can switch between them via the status bar at the bottom, or using the forge.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.

Buckets & Derivatives View

The Buckets & Derivatives 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:

  1. Create a new bucket to store your designs.

Note that bucket names must be globally unique. If you see a 409 Conflict error, you'll need to choose a different name.

Create bucket

  1. Upload a design to your bucket.

Upload design

  1. Translate the design for viewing.

Translate design

  1. Preview design derivatives in a new editor tab.

Preview design

Hubs & Derivatives View (Experimental)

Similar to the Buckets & Derivatives view, but using a 3-legged authentication instead, allowing the user to browse their existing design data hosted in BIM360, ACC, and other products built with the Autodesk Platform Services. In order for this view to be available, the user must first log into the currently active APS application with their Autodesk account. This can be done either by clicking the "APS Login" button in the bottom status bar, or by using the forge.login command. The extension will spin up a temporary web server on a preconfigured port (8123 by default), providing additional information about the login process, and waiting for a callback from the Autodesk servers.

Webhooks View

The Webhooks view can be used to browse and manage your webhooks in the Webhooks service.

Design Automation View

The Design Automation view can be used for browsing Design Automation entities such as app bundles or activities. It also provides a context menu that can be used to view additinal details of individual bundles or activities.

Known Limitations & Issues

Derivatives in Custom Regions, and Status Code 406

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.

Development

  • 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 Tools and the Developer: Reload Window commands.

Troubleshooting

Cannot Preview Re-translated Designs

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.