.NET에서 DocFX 정적 사이트 제공 및 인증 추가

DocFX 를 처음 사용하는 사용자를 위해 DocFX는 소스 코드 파일 및 마크다운에서 정적 사이트 생성기입니다. 주로 문서화에 사용되지만 다양한 목적으로 유연하게 사용할 수 있다는 점을 언급하는 것이 중요합니다. 일부는 블로깅, 프로필 사이트 등에 사용합니다. 무엇을 사용할지 정의하는 것은 실제로 귀하에게 달려 있습니다. DocFX에 대한 자세한 내용은 official website을 방문하십시오.

.NET에서 제공하는 이유는 무엇입니까?
정적 사이트 위에 다른 기능을 추가할 수 있는 기능을 제공하므로 DocFX에서 .NET에 의해 생성된 정적 사이트를 제공하는 데는 여러 가지 이점이 있습니다. 실용적인 이점 중 하나는 정적 사이트에 액세스하기 위한 인증을 추가하는 것입니다. 인증을 추가하는 이유는 회사에 내부 문서가 있고 승인된 사람만 액세스할 수 있도록 하려는 경우일 수 있습니다. 이 시나리오는 실제 사용 사례를 보여주기 위한 것이며 시나리오에 따라 사용 사례가 다를 수 있습니다. 그렇게 말하면 시작하겠습니다 ...

사전 요청

IdentityServer4 : 인증용

DocFX : 정적 사이트 생성용

원활한 빌드 프로세스를 위해 환경 변수에 DocFX를 추가합니다

.

이 기사에서는 인증에 IdentityServer4를 사용했지만 이 구현은 다른 인증 방법에서도 잘 작동합니다.

IdentityServer4 설정

IdentityServer4 프로젝트 만들기

dotnet new is4inmem -n Identity

IdentityServer4 프로젝트의 템플릿은 IdentityServer's Github repo에서 찾을 수 있습니다. ID 프로젝트가 생성되면 변경할 필요가 없습니다.

정적 사이트 서버 설정

ASP.NET Api 프로젝트 만들기

dotnet new webapi -n StaticSiteServer

Microsoft.AspNetCore.Authentication.OpenIdConnect Nuget 패키지에 대한 참조를 추가합니다.

인증을 설정할 때 여기저기서 몇 가지 변경 사항이 있습니다. 주제에서 벗어나지 않기 위해 이 기사에서는 다루지 않겠습니다. 그러나 소스 코드는 myGithub repository에서 찾을 수 있습니다.

정적 사이트 설정

StaticSiteServer와 동일한 디렉토리에 정적 사이트 프로젝트 생성

docfx init -q -o Docs

빌드 프로세스 설정

StaticSiteServer.csproj 파일 시스템의 루트 디렉토리를 정의하도록 업데이트DocFX

<PropertyGroup>
      .
      .
      .
    <DocFXRoot>Docs\</DocFXRoot>
</PropertyGroup>

빌드 및 게시 중에 정적 사이트를 생성하도록 StaticSiteServer.csproj를 업데이트합니다.

<ItemGroup>
        <Content Remove="$(DocFXRoot)**" />
        <None Remove="$(DocFXRoot)**" />
        <None Include="$(DocFXRoot)**" Exclude="$(DocFXRoot)_site\**" />
    </ItemGroup>
    <Target Name="DebugEnsureDocFXEnv" BeforeTargets="Build" Condition=" '$(Configuration)' == 'Debug' And !Exists('$(DocFXRoot)node_modules') ">
        <Exec Command="docfx --version" ContinueOnError="true">
            <Output TaskParameter="ExitCode" PropertyName="ErrorCode" />
        </Exec>
        <Error Condition="'$(ErrorCode)' != '0'" Text="DocFX is required to build and run this project. To continue, please install DocFX from https://github.com/dotnet/docfx/releases, and then restart your command prompt or IDE." />
        <Message Importance="high" Text="Generate static sites from Markdown and code files. This may take several minutes..." />
        <Exec WorkingDirectory="$(DocFXRoot)" Command="docfx build" />
    </Target>
    <Target Name="PublishRunWebpack" AfterTargets="ComputeFilesToPublish">
        <Exec WorkingDirectory="$(DocFXRoot)" Command="docfx build" />
        <ItemGroup>
            <DistFiles Include="$(DocFXRoot)_site\**" />
            <ResolvedFileToPublish Include="@(DistFiles->'%(FullPath)')" Exclude="@(ResolvedFileToPublish)">
                <RelativePath>%(DistFiles.Identity)</RelativePath>
                <CopyToPublishDirectory>PreserveNewest</CopyToPublishDirectory>
                <ExcludeFromSingleFile>true</ExcludeFromSingleFile>
            </ResolvedFileToPublish>
        </ItemGroup>
    </Target>   

이제 이러한 변경으로 인해 정적 사이트가 빌드 시간에 생성됩니다. 그러나 정적 사이트는 여전히 StaticSiteServer 웹 API의 서버가 아닙니다. 이를 위해 Startup.cs를 업데이트할 수 있습니다...ConfigureServices 메서드에서 인증 추가

public void ConfigureServices(IServiceCollection services)
{
  .
  .
  .
  services.AddAuthorization(options =>
              {
                  options.FallbackPolicy = new 
  AuthorizationPolicyBuilder()
                      .RequireAuthenticatedUser()
                      .Build();
              });
  .
  .
  .
}

다시 Startup.cs 파일에서 Configure 메서드를 업데이트하여 정적 파일을 제공합니다.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
 .
 .
 .
  app.UseFileServer(new FileServerOptions
              {
                  FileProvider = new 
  PhysicalFileProvider(
                  Path.Combine(env.ContentRootPath, 
  "Docs", "_site")),
              });
  .
  .
  .
}

NOTE app.UseFileServer* must be added after app.UseAuthentication() and app.UseAuthorization().

그게 다야. 이제 StaticSiteServer에 액세스하려고 하면 인증을 위해 사용자를 리디렉션합니다. 사용자가 인증되면 아래와 같이 정적 사이트가 표시됩니다.
1. 정적 사이트 서버

2. 인증 페이지

3. 문서 정적 사이트

4. 문서 정적 사이트


전체 소스 코드는 Github에서 찾을 수 있습니다.

읽어주셔서 감사합니다, 건배!