platform sdk aspnet hosting

Hosting a Platform SDK integration in ASP.NET

Use the Platform SDK in an ASP.NET server process by configuring assembly loading, selecting compatible native dependencies, and managing SDK objects during application startup and shutdown.

This guide covers classic ASP.NET on .NET Framework, ASP.NET Core, Internet Information Services (IIS), IIS Express, and self-hosted applications.

The examples use Security Center SDK 5.14 with .NET Framework 4.8.1 or .NET 10 on Windows. They construct an Engine and serve an HTTP response without logging on to Security Center. When adapting an example to another SDK version, select a framework supported by that version.

Hosting models and process architecture

Select the host process architecture to match the native SDK dependencies used by your application. The host settings differ between IIS, IIS Express, and a separate application executable.

Hosting model	Process that loads the SDK	Architecture selection
Classic ASP.NET in IIS Express	iisexpress.exe	Select the x86 or x64 IIS Express executable.
Classic ASP.NET in IIS	w3wp.exe	Configure the application pool's Enable 32-Bit Applications setting.
ASP.NET Core in IIS, in-process	w3wp.exe or iisexpress.exe	Match the application, installed runtime, and worker process architectures.
ASP.NET Core in IIS, out-of-process	Application executable or dotnet.exe	Select the architecture of the application process that IIS launches.
Self-hosted ASP.NET Core or .NET Framework HTTP application	Your executable or dotnet.exe	Select the executable and runtime architecture.

For IIS on 64-bit Windows, Enable 32-Bit Applications set to True selects a 32-bit worker process. False selects a 64-bit worker process. For out-of-process ASP.NET Core hosting, select the architecture of the separate application executable or dotnet.exe. See Adding application pools on Microsoft Learn.

For ASP.NET Core, see In-process hosting and Out-of-process hosting on Microsoft Learn. IIS deployments also require the ASP.NET Core Hosting Bundle for the deployed runtime.

Configuring SDK assembly loading

Install the SDK on the machine that executes the web application, or use an existing Security Center installation. For project references, the Copy Local setting, SDK discovery, and the sample resolvers, see Referencing SDK assemblies.

Use GSC_SDK with the .NET Framework resolver and GSC_SDK_CORE with the modern .NET resolver. When multiple SDK versions are installed, set the variable to the installation your application requires. Verify the environment variables available to the web process under its Windows account.

Set Copy Local to False for SDK references. Do not copy or redistribute SDK DLLs in the web application's bin directory or deployment package. Resolve them from the installed SDK or Security Center directory at runtime.

Register the resolver before executing code that uses SDK types. Keep fields that use SDK types out of the class that registers the resolver. Also keep SDK types out of the initial startup method's parameters, return type, and local variables. In the examples, a separate method marked NoInlining prevents SDK initialization code from being inlined into the method that registers the resolver.

The classic ASP.NET example registers the resolver in Application_Start. Assemblies loaded before that method runs must load without the resolver. Keep code that depends on the SDK out of dynamically compiled App_Code, inline page code, and startup components that execute before resolver registration. Compile that code in your application project. See ASP.NET application life cycle overview for IIS 7.0 on Microsoft Learn.

Working directories and native dependencies

The .NET Framework sample resolver changes the process working directory to the SDK installation. When an architecture subdirectory exists, it also adds that directory to the process PATH. Managed assembly resolution and native DLL lookup are separate; handling AssemblyResolve alone does not configure native dependency lookup.

Use absolute paths for application files. For classic ASP.NET, derive application paths from AppDomain.CurrentDomain.BaseDirectory or the ASP.NET path-mapping APIs. Avoid changing the working directory per request. Windows shares it across every thread in the process, including other applications in the same IIS worker process. Use a dedicated application pool for an integration that changes these process settings. See SetCurrentDirectory on Microsoft Learn.

Starting a classic ASP.NET application

This example uses a compiled .NET Framework application assembly and a minimal HTTP handler. It keeps one Engine for the application domain and disposes it during application shutdown. The status handler reads a string prepared during startup; it does not call the SDK on each request.

Before you begin, install the .NET Framework 4.8.1 targeting pack, .NET 10 SDK, Security Center SDK 5.14, and IIS Express. Set GSC_SDK to the SDK's .NET Framework installation directory. Run the example locally before adapting it to an existing application.

1. Create a folder named Classic and copy SdkResolverNetFramework.cs from the resolver linked on the assembly-reference page into it. Preserve the resolver's Genetec.Dap.CodeSamples namespace.

2. Create Classic.csproj in that folder:

   <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
       <TargetFramework>net481</TargetFramework>
       <LangVersion>latest</LangVersion>
       <AssemblyName>SdkWebBootstrap</AssemblyName>
       <OutputPath>site\bin\</OutputPath>
       <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
     </PropertyGroup>
     <ItemGroup>
       <Reference Include="System.Web" />
       <Reference Include="Genetec.Sdk">
         <HintPath>$(GSC_SDK)\Genetec.Sdk.dll</HintPath>
         <Private>False</Private>
       </Reference>
     </ItemGroup>
   </Project>

3. Create Bootstrap.cs in Classic:

   using System;
   using System.IO;
   using System.Runtime.CompilerServices;
   using System.Web;
   using Genetec.Dap.CodeSamples;
   
   namespace SdkWebBootstrap
   {
       public class WebApplication : HttpApplication
       {
           protected void Application_Start(object sender, EventArgs e)
           {
               SdkResolver.Initialize();
               SdkLifetime.Start();
           }
   
           protected void Application_End(object sender, EventArgs e)
           {
               SdkLifetime.Stop();
           }
       }
   
       public sealed class StatusHandler : IHttpHandler
       {
           public bool IsReusable { get { return true; } }
   
           public void ProcessRequest(HttpContext context)
           {
               context.Response.ContentType = "text/plain";
               context.Response.Write(SdkLifetime.Describe());
           }
       }
   
       public static class SdkLifetime
       {
           private static Genetec.Sdk.Engine engine;
           private static string status;
   
           [MethodImpl(MethodImplOptions.NoInlining)]
           public static void Start()
           {
               engine = new Genetec.Sdk.Engine();
               string architecture = Environment.Is64BitProcess ? "x64" : "x86";
               status = $"Engine constructed; process={architecture}; SDK={typeof(Genetec.Sdk.Engine).Assembly.GetName().Version}";
           }
   
           public static string Describe() { return status; }
   
           public static void Stop()
           {
               if (engine != null)
               {
                   engine.Dispose();
                   engine = null;
                   string logPath = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "App_Data", "lifecycle.txt");
                   File.AppendAllText(logPath, $"Engine disposed{Environment.NewLine}");
               }
           }
       }
   }

4. Create site\App_Data. Create site\Global.asax with this content:

   <%@ Application Language="C#" Inherits="SdkWebBootstrap.WebApplication" %>

5. Create site\status.ashx:

   <%@ WebHandler Language="C#" Class="SdkWebBootstrap.StatusHandler" %>

6. Create site\web.config:

   <configuration>
     <system.web>
       <compilation debug="false" targetFramework="4.8.1" />
       <httpRuntime targetFramework="4.8.1" />
       <customErrors mode="RemoteOnly" />
     </system.web>
   </configuration>

7. From the Classic folder, build and start 64-bit IIS Express. The commands assume IIS Express is installed in its default location:

   dotnet build .\Classic.csproj
   $sitePath = Join-Path (Get-Location).Path 'site'
   & "$env:ProgramFiles\IIS Express\iisexpress.exe" "/path:$sitePath" /port:18741 /systray:false

8. In another terminal, request the handler:

   (Invoke-WebRequest 'http://localhost:18741/status.ashx').Content

The response reports Engine constructed, the process architecture, and the SDK assembly version. Press Q in the IIS Express terminal to stop the application. On an orderly shutdown, the application writes Engine disposed to App_Data\lifecycle.txt.

For a 32-bit run, launch iisexpress.exe from ${env:ProgramFiles(x86)}\IIS Express and use a free port. Match the host to the SDK components used by your application.

Deploying the classic application to IIS

Use a dedicated application pool so other applications do not share the resolver's process settings.

1. Install the IIS ASP.NET 4.x components and the application's .NET Framework version.
2. Create an application pool with .NET CLR Version set to v4.0 and Managed Pipeline Mode set to Integrated. .NET Framework 4.8.1 uses CLR 4; IIS does not provide a v4.8.1 selection.
3. Set Enable 32-Bit Applications for the required process architecture.
4. Deploy the contents of site and assign the application to that pool.
5. Grant the pool identity read and execute access to the application and SDK installation. For this example, grant write access to the application's App_Data folder for the shutdown record.
6. Verify SDK discovery from the worker process and request status.ashx locally. Recycle only this application pool, and then request the handler again to confirm that startup repeats successfully.

For permissions under a pool identity, see Application pool identities on Microsoft Learn. Configure application credentials and file permissions for the deployment identity instead of relying on the interactive developer account.

Starting an ASP.NET Core application

ASP.NET Core provides an explicit entry point. Initialize the modern .NET resolver before registering or constructing services that use SDK types.

Before you begin, install the .NET 10 SDK and Security Center SDK 5.14. Set GSC_SDK_CORE to the SDK's net10.0-windows directory.

This example targets net10.0-windows. The project enables Windows Presentation Foundation (WPF) references to supply dependencies required by the SDK assemblies, even though the application runs as a web server. Recheck package dependencies when changing SDK or framework versions.

1. Create a folder named Core and copy SdkResolverNetCoreApp.cs from the assembly-reference page into it.

2. Create Core.csproj:

   <Project Sdk="Microsoft.NET.Sdk.Web">
     <PropertyGroup>
       <TargetFramework>net10.0-windows</TargetFramework>
       <ImplicitUsings>enable</ImplicitUsings>
       <Nullable>disable</Nullable>
       <UseWPF>true</UseWPF>
     </PropertyGroup>
     <ItemGroup>
       <Reference Include="Genetec.Sdk">
         <HintPath>$(GSC_SDK_CORE)\Genetec.Sdk.dll</HintPath>
         <Private>False</Private>
       </Reference>
       <PackageReference Include="Microsoft.Windows.Compatibility" Version="10.0.6" />
       <PackageReference Include="System.ServiceModel.Primitives" Version="10.0.652802" />
       <PackageReference Include="System.Runtime.Serialization.Formatters" Version="10.0.0" />
     </ItemGroup>
   </Project>

3. Create Program.cs:

   using System.Runtime.CompilerServices;
   using Genetec.Dap.CodeSamples;
   
   SdkResolver.Initialize();
   SdkWebHost.Run(args);
   
   static class SdkWebHost
   {
       [MethodImpl(MethodImplOptions.NoInlining)]
       public static void Run(string[] args)
       {
           WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
           builder.Services.AddSingleton<Genetec.Sdk.Engine>(services => new Genetec.Sdk.Engine());
           WebApplication app = builder.Build();
           Genetec.Sdk.Engine engine = app.Services.GetRequiredService<Genetec.Sdk.Engine>();
           string architecture = Environment.Is64BitProcess ? "x64" : "x86";
           string status = $"Engine constructed; process={architecture}; SDK={engine.GetType().Assembly.GetName().Version}";
           app.MapGet("/sdk-bootstrap", () => Results.Text(status));
           app.Run();
       }
   }

4. Build and run from the Core folder:

   dotnet build .\Core.csproj
   dotnet .\bin\Debug\net10.0-windows\Core.dll --urls http://127.0.0.1:18743

5. In another terminal, request the endpoint:

   (Invoke-WebRequest 'http://127.0.0.1:18743/sdk-bootstrap').Content

The response confirms Engine construction. Press Ctrl+C in the application terminal to stop the host. The dependency injection container owns the singleton created by the factory and disposes it when the host is disposed. See Dependency injection guidelines on Microsoft Learn.

For deployment, publish non-SDK package dependencies with the application and install the required .NET runtimes, including the Windows Desktop Runtime for this project. Do not rely on packages cached under a developer's user profile. Test the published application under its deployment account. Keep the diagnostic endpoint local during development or remove it when adding production routes.

Starting a self-hosted .NET Framework application

A self-hosted .NET Framework HTTP application controls its own startup. Initialize the .NET Framework resolver in the executable's entry point, and then call a separate method that constructs SDK objects and starts the HTTP server. Configure architecture and permissions for that executable; IIS application-pool settings do not apply.

Managing connections and application restarts

Add Security Center logon after resolver initialization and Engine construction. Configure the SDK certificate and evaluate the logon result before accepting operations that require a connection. See Connecting to Security Center and SDK certificates.

Use one application component to manage the Engine, connection readiness, reconnection, event subscriptions, and shutdown. Coordinate shared application state and follow the threading requirements of each SDK feature before allowing concurrent requests to use it.

Define authorization for each web operation. Browser authentication does not automatically select the Security Center user for a shared SDK connection.

Classic ASP.NET application state and ASP.NET Core singletons belong to one application instance. Multiple worker processes or server instances can each establish a separate SDK connection and event subscription. Account for that when scaling or using overlapping process recycling.

IIS can terminate or suspend idle worker processes, and application changes can restart classic ASP.NET. Consider a separate Windows service when monitoring must continue independently of website traffic or deployment. See Process model settings on Microsoft Learn.

For ASP.NET Core connection management, a hosted service can coordinate startup and shutdown with the web host. Stop accepting new operations, cancel or finish in-progress work, unsubscribe events, and dispose the Engine during orderly shutdown. Forced process termination can bypass shutdown callbacks, so recover from interrupted work on the next start. See Background tasks with hosted services on Microsoft Learn.