DOCSEARCHbyAlgolia
Submit Docs

Katana Documentation

repository·main·Indexed 21 days ago

https://github.com/aspnet/aspnetkatana

A collection of components for building and hosting OWIN-based web applications on the .NET Framework. Includes the Katana host, server, and middleware implementations, as well as tools like Microsoft.Owin.SelfHost for in-process hosting, OwinHost.exe for self-hosting applications, and TestServer for unit testing OWIN components in memory.

Tokens
1.6K
Snippets
6
Records
10
Agent score
74%

What's inside Katana

  1. Overview of Katana components

    main

    Katana is a flexible set of components designed for building and hosting OWIN-based web applications on the .NET Framework. It includes the Katana host, server, and various middleware components.

    Official releases and prerelease versions are available via NuGet. For a detailed breakdown of individual components, refer to the Packages Wiki.

  2. Configure OwinHost as a Web Server in Visual Studio 2013

    main

    In Visual Studio 2013, you can launch OwinHost directly using the F5 debugging gesture by registering it as a custom Web server.

    1. Install the OwinHost NuGet package in your Web application project.
    2. Open the Project Properties.
    3. Navigate to the Web tab.
    4. In the Servers dropdown list, select OwinHost.
    5. (Optional) Specify additional command line settings in the form fields provided below the server list.
    6. Press F5 to run the project using OwinHost.exe.

  3. Use Signed Rolling Builds for development

    main

    Rolling builds are provided via an alternate NuGet feed for developers who want to test new features or bug fixes before they reach an official prerelease or final build.

    Warning: Rolling builds are not intended for production use.

    Rolling Build NuGet Feed URL: https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-libraries/nuget/v3/index.json

  4. Build and run Katana from source

    main

    To build the project and execute the test suite from a command prompt, use the build.cmd script located in the root directory. Note that the build process may require downloading NuGet packages from the public NuGet.org feed.

    To open the solution in Visual Studio, run the startvs.cmd script found in the root directory.

    build.cmd
startvs.cmd

  5. Use TestServer to unit test OWIN components

    main

    The TestServer class is the primary tool for unit testing OWIN components. It allows you to create an OWIN request processing pipeline and submit requests that are processed directly in memory, bypassing the network stack.

    To use it, call TestServer.Create and provide an OwinStartup delegate to configure your pipeline (e.g., adding middleware or terminal endpoints). Once the server is created, you can interact with it using the HttpClient property or via fluent request builder methods.

    using(var server = TestServer.Create(app =>
                {
                    app.UseErrorPage(); // See Microsoft.Owin.Diagnostics
                    app.Run(context =>
                    {
                        return context.Response.WriteAsync("Hello world using OWIN TestServer");
                    });
                }))
            {
                HttpResponseMessage response = await server.HttpClient.GetAsync("/");
                // TODO: Validate response
            }

  6. Install and locate OwinHost.exe

    main

    The OwinHost package provides OwinHost.exe for self-hosting OWIN applications. You can install it via Visual Studio's NuGet Package Manager or via NuGet.exe for a global installation.

    Locating the executable

    • Visual Studio NuGet installation: The executable is located in the package's tools directory, typically at <solution root>/packages/OwinHost.(version)/tools.
    • Global installation: To avoid cumbersome path management when using the command line, install the package to a common location on your machine and add that directory to your PATH environment variable. This allows you to run OwinHost.exe from any project directory without path qualifiers.

  7. Launch an OWIN application with OwinHost.exe

    main

    To self-host an OWIN application, run OwinHost.exe from your Web application's project directory.

    Project Directory Definition: The directory must be the parent of the ./bin folder, which contains your application's assemblies and the selected server assembly.

    Default Behavior

    When running OwinHost.exe without parameters:

    1. It attempts to locate and load the application's startup class.
    2. It loads the OWIN HttpListener server.
    3. It begins listening on port 5000 after constructing the OWIN pipeline.
    OwinHost.exe

  8. Host OWIN HTTP components in your own process

    main

    Use the Microsoft.Owin.SelfHost libraries to host OWIN-compatible HTTP components directly within your own application process. This is achieved by using the WebApp.Start<TStartup> method, which takes a Startup class to configure the application pipeline and a base URI for the host.

    using (WebApp.Start<Startup>("http://localhost:12345"))
{
    Console.ReadLine();
}

public class Startup
{
    public void Configuration(IAppBuilder app)
    {
#if DEBUG
        app.UseErrorPage();
#endif
        app.UseWelcomePage("/");
    }
}

  9. Submit requests using the TestServer request builder

    main

    In addition to using the HttpClient property on a TestServer instance, you can use fluent helper methods to construct and submit requests. This is useful for quickly adding headers or other request properties before execution.

    HttpResponseMessage response = await server.CreateRequest("/")
                                           .AddHeader("header1", "headervalue1")
                                           .GetAsync();

  10. Customize OwinHost behavior with parameters

    main

    You can modify the default behavior of OwinHost.exe using command-line parameters. For example, to use an alternate OWIN-compatible server instead of the default HttpListener, use the -s flag followed by the assembly name.

    To view the full list of available options, run the executable with the /? flag.

    # Select a custom server assembly
OwinHost.exe -s <Custom.Server.Assembly>

# View help documentation
OwinHost.exe /?