ArbeitsbereicheWorkspaces

In einem Arbeitsbereich stellt Visual Studio eine beliebige Sammlung von Dateien im geöffneten Ordnerdar und wird durch den- IWorkspace Typ dargestellt.A workspace is how Visual Studio represents any collection of files in Open Folder, and it's represented by the IWorkspace type. Der Arbeitsbereich kennt nicht den Inhalt oder die Funktionen im Zusammenhang mit Dateien innerhalb des Ordners.By itself, the workspace doesn't understand the contents or features related to files within the folder. Vielmehr stellt Sie einen allgemeinen Satz von APIs für Features und Erweiterungen bereit, um Daten zu erzeugen und zu nutzen, auf die andere Benutzer reagieren können.Rather, it provides a general set of APIs for features and extensions to produce and consume data that others can act upon. Die Producer werden über die Managed Extensibility Framework (MEF) mithilfe verschiedener Export Attribute zusammengesetzt.The producers are composed through the Managed Extensibility Framework (MEF) using various export attributes.

Arbeitsbereichs Anbieter und-DiensteWorkspace providers and services

Arbeitsbereichs Anbieter und-Dienste stellen die Daten und Funktionen bereit, die auf den Inhalt eines Arbeitsbereichs reagieren sollen.Workspace providers and services provide the data and functionality to react to the contents of a workspace. Sie können kontextabhängige Dateiinformationen, Symbole in Quelldateien oder Buildfunktionen bereitstellen.They might provide contextual file information, symbols in source files, or build functionality.

Beide Konzepte verwenden ein Factorymuster und werden durch MEF durch den Arbeitsbereich importiert.Both concepts use a factory pattern and are imported through MEF by the workspace. Alle Export Attribute implementieren IProviderMetadataBase oder IWorkspaceServiceFactoryMetadata . es gibt jedoch konkrete Typen, die Erweiterungen für exportierte Typen verwenden sollten.All export attributes implement IProviderMetadataBase or IWorkspaceServiceFactoryMetadata, but there are concrete types that extensions should use for exported types.

Ein Unterschied zwischen Anbietern und Diensten ist die Beziehung zum Arbeitsbereich.One difference between providers and services is their relation to the workspace. Ein Arbeitsbereich kann viele Anbieter eines bestimmten Typs aufweisen, es wird jedoch nur ein Dienst eines bestimmten Typs pro Arbeitsbereich erstellt.A workspace can have many providers of a particular type, but only one service of a particular type is created per workspace. Ein Arbeitsbereich verfügt beispielsweise über viele Dateiscanner-Anbieter, aber der Arbeitsbereich verfügt über nur einen Indizierungs Dienst pro Arbeitsbereich.For example, a workspace has many file scanner providers but the workspace has only one indexing service per workspace.

Ein weiterer wichtiger Unterschied ist die Nutzung von Daten von Anbietern und Diensten.Another key difference is consumption of data from providers and services. Der Arbeitsbereich ist der Einstiegspunkt zum erhalten von Daten von Anbietern aus mehreren Gründen.The workspace is the entry point to get data from providers for a couple reasons. Zunächst verfügen Anbieter in der Regel über einen schmalen Satz von Daten, die Sie erstellen.First, providers typically have some narrow set of data they create. Bei den Daten kann es sich um Symbole für eine c#-Quelldatei oder um builddateikontexte für eine CMakeLists.txt Datei handeln.The data might be symbols for a C# source file or build file contexts for a CMakeLists.txt file. Der Arbeitsbereich entspricht der Anforderung eines Consumers an die Anbieter, deren Metadaten mit der Anforderung übereinstimmen.The workspace will match a consumer's request to the providers whose metadata align with the request. Zweitens ermöglichen einige Szenarien vielen Anbietern, an einer Anforderung mitzuwirken, während andere Szenarien den Anbieter mit der höchsten Priorität verwenden.Second, some scenarios allow for many providers to contribute to a request while others scenarios use the provider with highest priority.

Im Gegensatz dazu können Erweiterungen Instanzen von erhalten und direkt mit den Arbeitsbereichs Diensten interagieren.In contrast, extensions can get instances of and interact directly with workspace services. Erweiterungs Methoden für IWorkspace sind für die Dienste verfügbar, die von Visual Studio bereitgestellt werden, z GetFileWatcherService . b..Extension methods on IWorkspace are available for the services provided by Visual Studio, such as GetFileWatcherService. Ihre Erweiterung bietet möglicherweise einen Arbeitsbereichs Dienst für Komponenten innerhalb ihrer Erweiterung oder für andere Erweiterungen.Your extension may offer a workspace service for components within your extension or for other extensions to consume. Consumer sollten GetServiceAsync oder eine Erweiterungsmethode verwenden, die Sie für den IWorkspace Typ angeben.Consumers should use GetServiceAsync or an extension method you provide on the IWorkspace type.

Warnung

Erstellen Sie keine Dienste, die mit Visual Studio in Konflikt stehen.Do not author services that conflict with Visual Studio. Dies kann zu unerwarteten Problemen führen.It can lead to unexpected issues.

Entsorgung bei der Schließung des ArbeitsbereichsDisposal on workspace closure

Wenn ein Arbeitsbereich geschlossen wird, müssen Extender ggf. den asynchronen Code verwerfen, aber abrufen.On closure of a workspace, extenders might need to dispose but call asynchronous code. Die- IAsyncDisposable Schnittstelle ist verfügbar, damit Sie diesen Code leicht schreiben können.The IAsyncDisposable interface is available to make writing this code easy.

ArbeitsbereichseinstellungenWorkspace settings

Arbeitsbereiche verfügen IWorkspaceSettingsManager über einen Dienst mit einfacher, aber leistungsfähiger Kontrolle über einen Arbeitsbereich.Workspaces have an IWorkspaceSettingsManager service with simple but powerful control over a workspace. Eine grundlegende Übersicht über die Einstellungen finden Sie unter Anpassen von Build-und debugtasks.For a basic overview of settings, see Customize build and debug tasks.

Einstellungen für die meisten SettingsType Typen sind JSON -Dateien, z. b. VSWorkspaceSettings.json und tasks.vs.json.Settings for most SettingsType types are .json files, such as VSWorkspaceSettings.json and tasks.vs.json.

Die Leistungsfähigkeit der Arbeitsbereichs Einstellungen liegt bei "Bereichen", bei denen es sich einfach um Pfade innerhalb des Arbeitsbereichs handelt.The power of workspace settings centers around "scopes", which are simply paths within the workspace. Wenn ein Consumer aufruft GetAggregatedSettings , werden alle Bereiche, die den angeforderten Pfad und den Typ der Einstellung enthalten, aggregiert.When a consumer calls GetAggregatedSettings, all the scopes that include the requested path and type of setting are aggregated. Die Bereichs Aggregations Priorität lautet wie folgt:Scope aggregation priority is as follows:

  1. "Lokale Einstellungen", bei denen es sich in der Regel um das Stammverzeichnis des Arbeitsbereichs handelt .vs"Local settings", which is typically the workspace root's .vs directory.
  2. Der angeforderte Pfad selbst.The requested path itself.
  3. Das übergeordnete Verzeichnis des angeforderten Pfads.The parent directory of the requested path.
  4. Alle weiteren übergeordneten Verzeichnisse bis einschließlich des Arbeitsbereichs Stamms.All further parent directories up to and including the workspace root.
  5. "Globale Einstellungen", die sich in einem Benutzerverzeichnis befinden."Global settings", which is in a user directory.

Das Ergebnis ist eine Instanz von IWorkspaceSettings .The result is an instance of IWorkspaceSettings. Dieses Objekt enthält die Einstellungen für einen bestimmten Typ und kann zum Festlegen von Schlüsselnamen, die als gespeichert werden, abgefragt werden string .This object holds the settings for a particular type, and can be queried for setting key names stored as string. Die GetProperty Methoden und WorkspaceSettingsExtensions Erweiterungs Methoden erwarten, dass der Aufrufer den Typ des angeforderten Einstellungs Werts kennt.The GetProperty methods and WorkspaceSettingsExtensions extension methods expect the caller to know the type of the setting value being requested. Da die meisten Einstellungsdateien als JSON -Dateien beibehalten werden, verwenden viele Aufrufe string , bool , int und Arrays dieser Typen.As most settings files are persisted as .json files, many invocations will use string, bool, int, and arrays of those types. Objekttypen werden ebenfalls unterstützt.Object types are also supported. In diesen Fällen können Sie IWorkspaceSettings sich selbst als Typargument verwenden.In those cases, you can use IWorkspaceSettings itself as the type argument. Beispiel:For example:

{
  "intValue": 1,
  "stringValue": "s",
  "boolValue": true,
  "stringArray": [
    "s1",
    "s2"
  ],
  "nestedIWorkspaceSettings": {
    "nestedString": "ns"
  }
}

Angenommen, diese Einstellungen befinden sich imVSWorkspaceSettings.jseines Benutzers _ auf, auf_die Daten wie folgt zugegriffen werden kann:Assuming these settings were in a user's VSWorkspaceSettings.json, the data can be accessed as:

using System.Collections.Generic;
using Microsoft.VisualStudio.Workspace;
using Microsoft.VisualStudio.Workspace.Settings;

private static void ReadSettings(IWorkspace workspace)
{
    IWorkspaceSettingsManager settingsManager = workspace.GetSettingsManager();
    IWorkspaceSettings settings = settingsManager.GetAggregatedSettings(SettingsTypes.Generic);

    // result == WorkspaceSettingsResult.Success
    WorkspaceSettingsResult result = settings.GetProperty("intValue", out int intValue);
    result = settings.GetProperty("stringValue", out string stringValue);
    result = settings.GetProperty("boolValue", out bool boolValue);
    result = settings.GetProperty("stringArray", out string[] stringArray);
    result = settings.GetProperty("nestedIWorkspaceSettings", out IWorkspaceSettings nestedIWorkspaceSettings);
    result = nestedIWorkspaceSettings.GetProperty("nestedString", out string nestedString);

    // Extension method alternative using default values.
    int intValueOrDefault = settings.Property("intValue", /* default */ 42);

    // Missing key. result == WorkspaceSettingsResult.Undefined
    result = settings.GetProperty("missing", out string missing);

    // Wrong type for a key. result == WorkspaceSettingsResult.Error
    result = settings.GetProperty("intValue", out IWorkspaceSettings notSettings);

    // Special ability to union "stringArray" across all scopes.
    IEnumerable<string> allStringArray = settings.UnionPropertyArray<string>("stringArray");
}

Hinweis

Diese Einstellungs-APIs stehen nicht im Zusammenhang mit den im-Namespace verfügbaren APIs Microsoft.VisualStudio.Settings .These settings APIs are unrelated to the APIs available in the Microsoft.VisualStudio.Settings namespace. Die Arbeitsbereichs Einstellungen sind agnostisch des Hosts und verwenden Arbeitsbereichs spezifische Einstellungsdateien oder dynamische Einstellungs Anbieter.Workspace settings are agnostic of the host and use workspace-specific settings files or dynamic settings providers.

Bereitstellen dynamischer EinstellungenProviding dynamic settings

Erweiterungen können s bereitstellen IWorkspaceSettingsProvider .Extensions can provide IWorkspaceSettingsProviders. Mit diesen in-Memory-Anbietern können Erweiterungen Einstellungen hinzufügen oder andere außer Kraft setzen.These in-memory providers allow extensions to add settings or override others.

Der Export eines IWorkspaceSettingsProvider unterscheidet sich von anderen Arbeitsbereichs Anbietern.Exporting an IWorkspaceSettingsProvider is different than other workspace providers. Die Factory ist nicht, IWorkspaceProviderFactory und es gibt keinen speziellen Attributtyp.The factory is not IWorkspaceProviderFactory and there is no special attribute type. Implementieren Sie stattdessen, IWorkspaceSettingsProviderFactory und verwenden Sie [Export(typeof(IWorkspaceSettingsProviderFactory))] .Instead, implement IWorkspaceSettingsProviderFactory and use [Export(typeof(IWorkspaceSettingsProviderFactory))].

// Common workspace provider factory pattern
[ExportFeatureProvider(some, args, to, export)]
internal class MyProviderFactory : IWorkspaceProviderFactory<IFeatureProvider>
{
     IFeatureProvider CreateProvider(IWorkspace workspace) => new Provider(workspace);
}

// IWorkspaceSettingsProvider pattern
[Export(typeof(IWorkspaceSettingsProviderFactory))]
internal class MySettingsProviderFactory : IWorkspaceSettingsProviderFactory
{
    // 100 is typically the value used by built-in settings providers. Lower value is higher priority.
    int Priority => 100;

    IWorkspaceSettingsProvider CreateSettingsProvider(IWorkspace workspace) => new MySettingsProvider(workspace);
}

Tipp

Gibt beim Implementieren von Methoden, die zurückgeben IWorkspaceSettingsSource (wie IWorkspaceSettingsProvider.GetSingleSettings ), eine Instanz von anstelle von zurück IWorkspaceSettings IWorkspaceSettingsSource .When implementing methods that return IWorkspaceSettingsSource (like IWorkspaceSettingsProvider.GetSingleSettings), return an instance of IWorkspaceSettings rather than IWorkspaceSettingsSource. IWorkspaceSettings bietet weitere Informationen, die bei einigen Einstellungs Aggregationen nützlich sein können.IWorkspaceSettings provides more information that can be useful during some settings aggregations.

Empfohlene VorgehensweisenWorkspace suggested practices

  • Rückgabe von Objekten von IWorkspaceProviderFactory.CreateProvider oder ähnlichen APIs, die Ihren Workspace Kontext bei der Erstellung merken.Return objects from IWorkspaceProviderFactory.CreateProvider or similar APIs that remember their Workspace context when created. Anbieter Schnittstellen werden geschrieben, erwartet, dass dieses Objekt bei der Erstellung beibehalten wird.Providers interfaces are written expecting this object is kept on creation.
  • Speichern Sie Arbeitsbereichs spezifische Caches oder Einstellungen im Pfad "lokale Einstellungen" des Arbeitsbereichs.Save workspace-specific caches or settings within the "Local settings" path of the workspace. Erstellen Sie einen Pfad für die Datei, indem Sie Microsoft.VisualStudio.Workspace.WorkspaceHelper.MakeRootedUnderWorkingFolder in Visual Studio 2017, Version 15,6 oder höher, verwenden.Create a path for your file using Microsoft.VisualStudio.Workspace.WorkspaceHelper.MakeRootedUnderWorkingFolder in Visual Studio 2017 version 15.6 or later. Verwenden Sie für Versionen vor Version 15,6 den folgenden Code Ausschnitt:For versions prior to version 15.6, use the following snippet:
using System.IO;
using Microsoft.VisualStudio.Workspace;
using Microsoft.VisualStudio.Workspace.Settings;

private static string MakeRootedUnderWorkingFolder(IWorkspace workspace, string relativePath)
{
    string workingFolder = workspace.GetSettingsManager().GetAggregatedSettings(SettingsTypes.WorkspaceControlSettings).Property<string>("WorkingFolder");
    return Path.Combine(workingFolder, relativePath);
}

Projektmappenereignisse und Automatisches Laden von PaketenSolution events and package auto-load

Geladene Pakete können implementieren IVsSolutionEvents7 und aufrufen IVsSolution.AdviseSolutionEvents .Loaded packages can implement IVsSolutionEvents7 and invoke IVsSolution.AdviseSolutionEvents. Dies schließt Ereignisse beim Öffnen und Schließen eines Ordners in Visual Studio ein.It includes eventing on opening and closing a folder in Visual Studio.

Ein Benutzeroberflächen Kontext kann verwendet werden, um das Paket automatisch zu laden.A UI context can be used to auto-load your package. Der Wert ist 4646B819-1AE0-4E79-97F4-8A8176FDD664.The value is 4646B819-1AE0-4E79-97F4-8A8176FDD664.

ProblembehandlungTroubleshooting

Das sourceexplorerpackage-Paket wurde nicht ordnungsgemäß geladen.The SourceExplorerPackage package did not load correctly

Die Erweiterbarkeit von Arbeitsbereichen ist hochgradig MEF-basiert, und Kompositions Fehler bewirken, dass das Paket, das den geöffneten Ordner gehostet, nicht geladen wird.Workspace extensibility is heavily MEF-based, and composition errors will cause the package hosting Open Folder to fail to load. Wenn eine Erweiterung z. b. einen Typ mit exportiert ExportFileContextProviderAttribute , der Typ jedoch nur implementiert IWorkspaceProviderFactory<IFileContextActionProvider> , tritt ein Fehler auf, wenn versucht wird, einen Ordner in Visual Studio zu öffnen.For example, if an extension exports a type with ExportFileContextProviderAttribute, but the type only implements IWorkspaceProviderFactory<IFileContextActionProvider>, an error will occur when trying to open a folder in Visual Studio.

Fehlerdetails finden Sie unter " %LocalAppData%\microsoft\visualstudio\15.0_id \componentmodelcache\microsoft.VisualStudio.default.err".Error details can be found in %LOCALAPPDATA%\Microsoft\VisualStudio\15.0_id\ComponentModelCache\Microsoft.VisualStudio.Default.err. Beheben Sie alle Fehler für Typen, die von ihrer Erweiterung implementiert werden.Resolve any errors for types implemented by your extension.

Fehlerdetails finden Sie unter " %LocalAppData%\microsoft\visualstudio\16.0_id \componentmodelcache\microsoft.VisualStudio.default.err".Error details can be found in %LOCALAPPDATA%\Microsoft\VisualStudio\16.0_id\ComponentModelCache\Microsoft.VisualStudio.Default.err. Beheben Sie alle Fehler für Typen, die von ihrer Erweiterung implementiert werden.Resolve any errors for types implemented by your extension.

Nächste SchritteNext steps

  • Datei Kontexte : Datei Kontext Anbieter bringen Code Intelligenz für geöffnete Ordner Arbeitsbereiche.File contexts - File context providers bring code intelligence for Open Folder workspaces.
  • Indizierung : die Arbeitsbereichs Indizierung sammelt und speichert Informationen über den Arbeitsbereich.Indexing - Workspace indexing collects and persists information about the workspace.