# File Explorer
## End user facing:
[Please visit our overview](https://aka.ms/PowerToysOverview_FileExplorerAddOns)
## Developing
We have already done most of the development work in the [PreviewHandlerCommon](./common/cominterop/IPreviewHandler.cs) common project. To add a preview for the file type of .xyz:
- Add a new .NET project in the preview pane folder.
- Add a reference to the `PreviewHandlerCommon` common project.
- Create your preview handler class and extend the FileBasedPreviewHandler class. See an example below:
```csharp
using System;
using System.Runtime.InteropServices;
using Common;
namespace XYZPreviewHandler
{
///
/// Implementation of preview handler for .xyz files.
/// GUID = CLSID / CLASS ID.
///
[Guid("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx")]
[ClassInterface(ClassInterfaceType.None)]
[ComVisible(true)]
public class XYZPreviewHandler : FileBasedPreviewHandler
{
private XYZPreviewHandlerControl xyzPreviewHandlerControl;
/// Call your rendering method here.
public override void DoPreview()
{
this.xyzPreviewHandlerControl.DoPreview(this.FilePath);
}
protected override IPreviewHandlerControl CreatePreviewHandlerControl()
{
this.xyzPreviewHandlerControl = new xyzPreviewHandlerControl();
return this.xyzPreviewHandlerControl;
}
}
}
```
Create a separate Preview Handler Control class and extend the `FormHandlerControl` Class.
```csharp
using Common;
namespace XYZPreviewHandler
{
public class XYZPreviewHandlerControl : FormHandlerControl
{
public XYZPreviewHandlerControl()
{
// ... do your initializations here.
}
public override void DoPreview(T dataSource)
{
// ... add your preview rendering code here.
}
}
}
```
#### Integrate the Preview Handler into PowerToys Settings:
Navigate to the [powerpreview](../previewpane/powerpreview/powerpreview.h) project and edit the `powerpreview.h` file. Add the following Settings Object instance to `m_previewHandlers` settings objects array in the constructor initialization:
```cpp
// XYZ Preview Handler Settings Object.
FileExplorerPreviewSettings(
false,
L"<--YOUR_TOGGLE_CONTROL_ID-->",
L"<--A description of your preview handler-->",
L"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx", // your preview handler CLSID.
L"<--A display name for your preview handler-->")
```
## Installation
### MSI (Recommended)
To add a new Previewer update the `Product.wxs` file in `PowerToysSetup` similar to existing Previewer to register the Preview Handler. More details about registration of Preview Handlers can be [found here.](https://docs.microsoft.com/en-us/windows/win32/shell/how-to-register-a-preview-handler)
```xml
```
### Directly registering/unregistering DLL's
**[Important] This method of registering Preview Handler DLL's is not recommended. It could lead to registry corruption.**
#### Registering Preview Handler
1. Restart Visual studio as administrator.
2. Sign `XYZPreviewHandler` and it's dependencies. To sign an assembly in VS, follow steps given [here](https://docs.microsoft.com/en-us/dotnet/standard/assembly/sign-strong-name#create-and-sign-an-assembly-with-a-strong-name-by-using-visual-studio).
3. Build `XYZPreviewHandler` project.
4. Open developer command prompt from `Tools > Command Line > Developer Command Prompt`.
5. Run following command for each nuget and project dependency to add them to Global Assembly Cache(GAC).
```
gacutil -i
```
6. Run following commands to register preview handler.
```
cd C:\Windows\Microsoft.NET\Framework64\4.0.x.x
gacutil -i
RegAsm.exe /codebase
```
7. Restart Windows Explorer process.
#### Unregistering Preview Handler
1. Run following commands in elevated developer command prompt to unregister preview handler.
```
cd C:\Windows\Microsoft.NET\Framework64\4.0.x.x
RegAsm.exe /unregister
gacutil -u XYZPreviewHandler
```
## Debugging
Since in-process preview handlers run under a surrogate hosting process (prevhost.exe by default), to debug a preview handler, you need to attach the debugger to the host process.
1. Click on a file with registered extension to start host process.
2. Attach debugger in Visual studio from `Debug->Attach to Process` and select `prevhost.exe` with type `Managed(version), x64`.
## Managing Preview Handlers
After successful integration, your preview handler should appear in the PowerToys settings UI under the `File Explorer Preview` Tab. In here you should be able to enable and disable all the preview handles.
