Share via

IVsSettingsWriter Interface

  • Article

Provides VSPackages a mechanism for storing configuration information in the Visual Studio settings file.

Namespace:  Microsoft.VisualStudio.Shell.Interop
Assembly:  Microsoft.VisualStudio.Shell.Interop.8.0 (in Microsoft.VisualStudio.Shell.Interop.8.0.dll)

Syntax

'Declaration
<GuidAttribute("0F1CF980-AFC6-406E-958D-7F24287E3916")> _
<InterfaceTypeAttribute()> _
Public Interface IVsSettingsWriter

[GuidAttribute("0F1CF980-AFC6-406E-958D-7F24287E3916")]
[InterfaceTypeAttribute()]
public interface IVsSettingsWriter

[GuidAttribute(L"0F1CF980-AFC6-406E-958D-7F24287E3916")]
[InterfaceTypeAttribute()]
public interface class IVsSettingsWriter

[<GuidAttribute("0F1CF980-AFC6-406E-958D-7F24287E3916")>]
[<InterfaceTypeAttribute()>]
type IVsSettingsWriter =  interface end

public interface IVsSettingsWriter

The IVsSettingsWriter type exposes the following members.

Methods

  Name Description
Public method ReportError Reports the error status of the settings file write operation.
Public method WriteCategoryVersion Sets the value of a category version object stored in the Visual Studio settings file.
Public method WriteSettingAttribute
Public method WriteSettingBoolean Stores the value of a Boolean object in the Visual Studio settings file.
Public method WriteSettingBytes Stores the values of an array in the Visual Studio settings file.
Public method WriteSettingLong Stores the value of a Long object in the Visual Studio settings file.
Public method WriteSettingString Stores a string value in the Visual Studio settings file.
Public method WriteSettingXml Stores the value of an XML object in the Visual Studio settings file.
Public method WriteSettingXmlFromString Stores the value of an XML setting as a string object in the Visual Studio settings file.

Top

Remarks

This interface is implemented by the environment.

Notes for Callers

Call IVsSettingsWriter when storing a VSPackage's configuration information into the Visual Studio settings file.

Notes for Implementers

Only VSPackages that have registered their support for the Visual Studio settings mechanism make use of IVsSettingsWriter. For more information on registering a VSPackage as supporting the Visual Studio settings mechanism, see Persisting Settings.

When a setting export operation has been selected from the Import/Export Settings feature available on the IDE’s Tools menu, the environment passes a IVsSettingsWriter interface to a VSPackage's settings export method, which uses the interface to write out configuration data. The Visual Studio SDK supports several export methods:

  • For interop assembly based VSPackages, the export method is the VSPackage's implementation of the IVsUserSettings interface's ExportSettings.

  • For most Managed Package Framework based VSPackages, the export method is the VSPackage's implementation of the IProfileManager interface's SaveSettingsToXml.

  • For Managed Package Framework based VSPackages implementing the DialogPage interface, the export method is that interface's SaveSettingsToXml.

For more information, see How to: Export Settings By Using Interop Assemblies or How to: Export Settings By Using the Managed Package Framework.

Note

In addition to any data stored by using IVsSettingsWriter methods, the IDE always transparently stores the version of Visual Studio used to export configuration data.

Note

Best practice when storing buffers or string is to save the size of the stored buffer or string as well as with the object itself. This size information should always be used when retrieving the saved buffer of string to avoid buffer overruns.

Examples

In the example below is a method called by an implementation of ExportSettings, the method writes out three settings values, one of which is the size of a buffer to be stored.

HRESULT ExportSettings_CommandBars(IVsSettingsWriter *pSettings)
{
    if (!pSettings)
        return E_INVALIDARG;
    
    hr = pSettings->WriteSettingString(c_szFirstSettingName, L"Value1");
    IfFailGo(hr);
    
    int cRandomTrash = 12345;
    BYTE *pRandomTrash = (BYTE *)VSAlloc(cRandomTrash);
    if (pRandomTrash){
        hr = pSettings->WriteSettingBytes(c_szRandomTrashBytes, pRandomTrash, cRandomTrash);
        IfFailGo(hr);
        hr = pSettings->WriteSettingLong(c_szRandomTrashLength, cRandomTrash);
        IfFailGo(hr);
    }
    
 Error:
    return hr;
};

See Also

Reference

Microsoft.VisualStudio.Shell.Interop Namespace

IVsSettingsReader

ExportSettings

Other Resources

Persisting Settings

How to: Export Settings By Using Interop Assemblies

How to: Export Settings By Using the Managed Package Framework

Working with Settings