Skip to content

Hosting

Jump to bottom Edit New page
Petr Švihlík edited this page May 20, 2026 · 3 revisions

Hosting Options

The recommended way to run WopiHost during development is via .NET Aspire (dotnet run --project infra/WopiHost.AppHost) — see the top-level README. This page covers everything else: running individual projects, IIS, Docker, HTTPS.

Running individual projects

If you'd rather not orchestrate via Aspire:

# Terminal 1 — backend
dotnet run --project sample/WopiHost

# Terminal 2 — frontend
dotnet run --project sample/WopiHost.Web

# Terminal 3 — validator (optional)
dotnet run --project sample/WopiHost.Validator

Make sure Wopi:ClientUrl and Wopi:HostUrl are wired up correctly in sample/WopiHost/appsettings.Development.json — without Aspire there's no service-discovery glue.

Command line (dotnet run)

# Set environment variables
export ASPNETCORE_ENVIRONMENT=Development
export ASPNETCORE_URLS=http://localhost:5000

# Run the application
dotnet run --project sample/WopiHost

Troubleshooting:

  • Ensure all configuration files are present in the project directory.
  • Check that appsettings.json contains valid WOPI configuration — see Configuration.
  • Use --verbosity detailed for detailed error information: dotnet run --project sample/WopiHost --verbosity detailed
  • Verify the WOPI client URL is accessible from the host.
  • Verify the storage provider's root path / connection string exists and is accessible.

IIS hosting

For production deployments on Windows Server with IIS:

  1. Publish the application:

    dotnet publish sample/WopiHost -c Release -o ./publish

  2. Create web.config:

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath="dotnet" arguments=".\WopiHost.dll" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

  3. Configure IIS:

    • Create a new Application Pool targeting .NET CLR Version "No Managed Code".
    • Create a new website pointing to the published folder.
    • Ensure the Application Pool identity has read/execute permissions.
    • Install the ASP.NET Core Hosting Bundle on the server.

  4. Configure WOPI settings in appsettings.json for your production environment:

    {
  "Wopi": {
    "ClientUrl": "https://your-office-online-server.com",
    "StorageProvider": {
      "RootPath": "C:\\WopiHost\\Documents"
    }
  }
}

    Provider selection lives in Program.cs, not in appsettings.json. Reference the provider package(s) you want and call their typed extensions at composition time — e.g.:

    builder.Services.AddFileSystemStorageProvider(builder.Configuration);
builder.Services.AddMemoryLockProvider();

    See Extending WopiHost for the full list of bundled extensions.

    IIS in-process gotcha. When hosting under IIS in-process, set Wopi:EmptyLockHeaderValue to " " (single space). IIS in-process strips empty header values before they hit the wire, which breaks WOPI clients that expect X-WOPI-Lock present on GetLock of an unlocked file. Out-of-process and reverse-proxy hosting preserve empty headers — keep the spec-correct empty-string default in those cases.

HTTPS configuration

To enable HTTPS for production deployments:

  1. Configure SSL certificates in your hosting environment.

  2. Update appsettings.json:

    {
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://localhost:5001",
        "Certificate": {
          "Path": "path/to/certificate.pfx",
          "Password": "certificate-password"
        }
      }
    }
  }
}

  3. Enable HTTPS redirection in Program.cs:

    app.UseHttpsRedirection();

  4. For IIS with HTTPS:

    • Configure SSL binding in IIS Manager.
    • Ensure the certificate is properly installed and trusted.
    • Update WOPI client URLs to use HTTPS.

Docker

A minimal Dockerfile for the backend:

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["sample/WopiHost/WopiHost.csproj", "sample/WopiHost/"]
RUN dotnet restore "sample/WopiHost/WopiHost.csproj"
COPY . .
WORKDIR "/src/sample/WopiHost"
RUN dotnet build "WopiHost.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "WopiHost.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "WopiHost.dll"]

Build and run:

docker build -t wopihost .
docker run -p 5000:80 wopihost

Older runtimes

WopiHost is single-targeted on net10.0 — libraries, sample apps, infra, and tests. The v8 line was the last to support net8.0 / net9.0; v9 onward is net10 only. For older runtimes, use a release tag:

Add a custom footer
Add a custom sidebar

Clone this wiki locally