|
| 1 | +--- |
| 2 | +title: "Workspace build in Visual Studio | Microsoft Docs" |
| 3 | +ms.custom: "" |
| 4 | +ms.date: "02/21/2018" |
| 5 | +ms.reviewer: "" |
| 6 | +ms.suite: "" |
| 7 | +ms.technology: |
| 8 | + - "vs-ide-sdk" |
| 9 | +ms.tgt_pltfrm: "" |
| 10 | +ms.topic: "article" |
| 11 | +ms.assetid: 813f7a5e-f298-4469-9f4c-a5bddf5a6e14 |
| 12 | +author: "vukelich" |
| 13 | +ms.author: "svukel" |
| 14 | +manager: "viveis" |
| 15 | +ms.workload: |
| 16 | + - "vssdk" |
| 17 | +--- |
| 18 | +# Workspace build |
| 19 | + |
| 20 | +Build support in [Open Folder](../ide/develop-code-in-visual-studio-without-projects-or-solutions.md) scenarios requires an extender to supply [indexed](workspace-indexing.md) and [file context](workspace-file-contexts.md) data for the [workspace](workspaces.md), as well as the build action to run. |
| 21 | + |
| 22 | +Below is an outline of what your extension will need. |
| 23 | + |
| 24 | +## Build file context |
| 25 | + |
| 26 | +- Provider factory |
| 27 | + - `ExportFileContextProviderAttribute` attribute with `supportedContextTypeGuids` as all applicable `string` constants from `BuildContextTypes` |
| 28 | + - Implements `IWorkspaceProviderFactory<IFileContextProvider>` |
| 29 | + - File context provider |
| 30 | + - Return a `FileContext` for each build operation and configuration supported |
| 31 | + - `contextType` from <xref:Microsoft.VisualStudio.Workspace.Build.BuildContextTypes> |
| 32 | + - `context` implements <xref:Microsoft.VisualStudio.Workspace.Build.IBuildConfigurationContext> with the `Configuration` property as the build configuration (for example `"Debug|x86"`, `"ret"`, or `null` if not applicable). Alternatively, use an instance of <xref:Microsoft.VisualStudio.Workspace.Build.BuildConfigurationContext>. The configuration value **must** match the configuration from the indexed file data value. |
| 33 | + |
| 34 | +## Indexed build file data value |
| 35 | + |
| 36 | +- Provider Factory |
| 37 | + - `ExportFileScannerAttribute` attribute with `IReadOnlyCollection<FileDataValue>` as a supported type |
| 38 | + - Implements `IWorkspaceProviderFactory<IFileScanner>` |
| 39 | +- File scanner on `ScanContentAsync<T>` |
| 40 | + - Returns data when `FileScannerTypeConstants.FileDataValuesType` is the type argument |
| 41 | + - Returns a file data value for each configuration constructed with: |
| 42 | + - `type` as `BuildConfigurationContext.ContextTypeGuid` |
| 43 | + - `context` as your build configuration (for example `"Debug|x86"`, `"ret"`, or `null` if not applicable). This value **must** match the configuration from the file context. |
| 44 | + |
| 45 | +## Build file context action |
| 46 | + |
| 47 | +- Provider factory |
| 48 | + - `ExportFileContextActionProvider` attribute with `supportedContextTypeGuids` as all applicable `string` constants from `BuildContextTypes` |
| 49 | + - Implements `IWorkspaceProviderFactory<IFileContextActionProvider>` |
| 50 | +- Action provider on `IFileContextActionProvider.GetActionsAsync` |
| 51 | + - Return an `IFileContextAction` that matches the given `FileContext.ContextType` value |
| 52 | +- File context action |
| 53 | + - Implements `IFileContextAction` and <xref:Microsoft.VisualStudio.Workspace.Extensions.VS.IVsCommandItem> |
| 54 | + - `CommandGroup` property returns `16537f6e-cb14-44da-b087-d1387ce3bf57` |
| 55 | + - `CommandId` is `0x1000` for build, `0x1010` for rebuild, or `0x1020` for clean |
| 56 | + |
| 57 | +>[!NOTE] |
| 58 | +>Since the `FileDataValue` needs to be indexed, there will be some amount of time between opening the workspace and the point at which the file is scanned for full build functionality. The delay will be seen on the first opening of a folder because there is no previously cached index. |
| 59 | +
|
| 60 | +## Reporting messages from a build |
| 61 | + |
| 62 | +The build can surface information, warning, and error messages to users one of two ways. The simple way is to use the <xref:Microsoft.VisualStudio.Workspace.Build.IBuildMessageService> and provide a <xref:Microsoft.VisualStudio.Workspace.Build.BuildMessage>, like so: |
| 63 | + |
| 64 | +```csharp |
| 65 | +using Microsoft.VisualStudio.Workspace; |
| 66 | +using Microsoft.VisualStudio.Workspace.Build; |
| 67 | + |
| 68 | +private static void OutputBuildMessage(IWorkspace workspace) |
| 69 | +{ |
| 70 | + IBuildMessageService buildMessageService = workspace.GetBuildMessageService(); |
| 71 | + |
| 72 | + if (buildMessageService != null) |
| 73 | + { |
| 74 | + // Example error build message. See the documentation for BuildMessage for more information. |
| 75 | + var message = new BuildMessage() |
| 76 | + { |
| 77 | + Type = BuildMessage.TaskType.Error, |
| 78 | + Code = "MY1001", |
| 79 | + TaskText = "This is a sample error", |
| 80 | + ProjectFile = "buildfile.bld", |
| 81 | + File = "sourcefile.src" |
| 82 | + LogMessage = $"This is sample text that will only go to the Build output window pane.\n" |
| 83 | + |
| 84 | + // And any other properties to set |
| 85 | + }; |
| 86 | + |
| 87 | + buildMessageService.ReportBuildMessages(new BuildMessage[] { message }); |
| 88 | + } |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +`BuildMessage.Type` and `BuildMessage.LogMessage` control the behavior of where information is presented to the user. Any `BuildMessage.TaskType` value other than `None` will produce an **Error List** entry with the given details. `LogMessage` will always be output in the **Build** pane of the **Output** tool window. |
| 93 | + |
| 94 | +Alternatively, extensions can directly interact with the **Error List** or **Build** pane. A bug exists in versions prior to Visual Studio 2017 Version 15.7 where the `pszProjectUniqueName` argument of <xref:Microsoft.VisualStudio.Shell.Interop.IVsOutputWindowPane2.OutputTaskItemStringEx2*> is ignored. |
| 95 | + |
| 96 | +>[!WARNING] |
| 97 | +>Callers of `IFileContextAction.ExecuteAsync` can provide arbitrary underlying implementations for the `IProgress<IFileContextActionProgressUpdate>` argument. Never invoke `IProgress<IFileContextActionProgressUpdate>.Report(IFileContextActionProgressUpdate)` directly. There are currently no general guidelines for using this argument, but these guidelines are subject to change. |
| 98 | +
|
| 99 | +## Build related APIs |
| 100 | + |
| 101 | +- <xref:Microsoft.VisualStudio.Workspace.Build.IBuildConfigurationContext> provides build configuration details. |
| 102 | +- <xref:Microsoft.VisualStudio.Workspace.Build.IBuildMessageService> shows <xref:Microsoft.VisualStudio.Workspace.Build.BuildMessage>s to users. |
| 103 | + |
| 104 | +## tasks.vs.json and launch.vs.json |
| 105 | + |
| 106 | +For information on authoring a tasks.vs.json or launch.vs.json file, see [Customize build and debug tasks](../ide/customize-build-and-debug-tasks-in-visual-studio.md). |
| 107 | + |
| 108 | +## Next steps |
| 109 | + |
| 110 | +* [Language Server Protocol](language-server-protocol.md) - Learn how to integrate language servers into Visual Studio. |
0 commit comments